msf£ 



DATATRIEVE-11 
Reference Manual 

Order No. AA-U049A-TK 



SHREWSBURY 




DECLIT AA CROSS U049A 

DAT AT R I EVE —11 Reference 
Manual 



Digital Equipment Corporation 
SHREWSBURY LIBRARY 



DATATRIEVE-11 
Reference Manual 

Order No. AA-U049A-TK 



September 1983 

This manual contains reference information for DATATRIEVE-11. 



OPERATING SYSTEM AND VERSION: RSX-11M 

RSX-11M PLUS 
RSTS/E 

SOFTWARE VERSION: DATATRIEVE-11 V3 



digital equipment corporation, maynard, massachusetts 



The information in this document is subject to change without notice and 
should not be construed as a commitment by Digital Equipment Corporation. 
Digital Equipment Corporation assumes no responsibility for any errors that 
may appear in this document. 

The software described in this document is furnished under a license and may 
be used or copied only in accordance with the terms of such license. 

No responsibility is assumed for the use or reliability of software on equip- 
ment that is not supplied by DIGITAL or its affiliated companies. 



Copyright © 1983 by Digital Equipment Corporation. All Rights Reserved. 



The postage-paid READER'S COMMENTS form on the last page of this docu- 
ment requests your critical evaluation to assist us in preparing future 
documentation. 



The following are trademarks of Digital Equipment Corporation: 




MASSBUS 



TM 



DECwriter 

DIBOL 

UNIBUS 



RSTS 
RSX 

DECmate 
DECsystem-10 
DECSYSTEM-20 
DECUS 

Work Processor 



Professional 
DEC 



PDP 

P/OS 



VAX 
VMS 
VT 



Rainbow 



DATATRIEVE-11 DOCUMENTATION MAP 



Intermediate 
Applications 



Advanced 
Applications 



User^] 
Guide 



Guide to 
Writing 
Reports 



Pocket 
Guidel 



Reference 
Manuall 



Call Interface 
Manual 



Getting 
Started 



Learning 
the Basics 



Summary 
Description 



ry] 



Installation 
Guide/ 
Release Notes 



Introduction 



DATATRIEVE-11 DOCUMENTATION DESCRIPTION 



GETTING STARTED 



Summary Description 

Provides an overview of DATATRIEVE. 
Contains a documentation directory, a 
glossary, and the master index. 



Installation Guide /Release Notes 

Describes the installation procedure and 
the installation verification procedure. 
Release Notes contain the latest informa- 
tion about new features, restrictions, and 
performance guidelines. 



LEARNING THE BASICS 

I 



Introduction to 
DATATRIEVE-11 

Interactively guides users through the 
basic tasks of managing information with 
DATATRIEVE. 



INTERMEDIATE APPLICATIONS 

I 

User's Guide 

Explains how to define, store, retrieve, 
modify, and restructure data using 
DATATRIEVE. Elaborates on material 
covered in the Introduction. 



Guide to Writing Reports 

Explains how to produce reports based on 
data managed by DATATRIEVE. De- 
scribes the instructions that specify the 
format and content of a report. 



Pocket Guide 

Provides a quick reference guide for expe- 
rienced users to the syntax and elements 
of DATATRIEVE. 



ADVANCED APPLICATIONS 



Reference Manual 

Provides full descriptions of the com- 
mands, statements, clauses, and other 
syntax elements that comprise the 
DATATRIEVE data management lan- 
guage. 



Call Interface Manual 

Explains how to call DATATRIEVE from 
programs in languages such as 
FORTRAN, COBOL, and BASIC. 
Describes how to use DATATRIEVE 
interactively on another node. 



iv 



Contents 

Page 

How to Use This Manual xi 

1 Introduction to the DATATRIEVE Language 

1.1 Introduction 1-1 

1.2 Starting and Ending a DATATRIEVE Session 1-1 

1.3 Commands and Statements 1-2 

1.3.1 The DATATRIEVE Character Set 1-4 

1.3.2 Command and Statement Elements 1-5 

1.3.2.1 Keywords 1-5 

1.3.2.2 Names 1-5 

1.3.2.3 Termination and Continuation Characters 1-6 

1.3.2.4 Comments 1-7 

1.3.3 DATATRIEVE Procedures 1-7 

1.4 DATATRIEVE Prompts 1-8 

1.4.1 Input Line Prompts 1-8 

1.4.2 Syntax Prompts 1-9 

1.4.3 Prompts for Storing and Modifying Values 1-9 

1.5 Data Files and DATATRIEVE Record Definitions 1-9 

1.6 DATATRIEVE Domains 1-10 

1.7 ADT, the Application Design Tool 1-10 

1.8 DATATRIEVE Tables 1-11 

1.9 The DATATRIEVE- 1 1 Report Writer 1-11 

1.10 The DATATRIEVE- 1 1 Editor 1-11 

1.11 The DATATRIEVE-11 Remote Access Interface 1-12 

2 Value Expressions and Boolean Expressions 

2.1 Introduction 2-1 

2.2 Value Expressions 2-1 

2.2.1 Character String Literals 2-2 

2.2.2 Numeric Literals . . 2-3 

2.2.3 Field Names 2-3 

2.2.3.1 Elementary and REDEFINES Field Names 2-3 

2.2.3.2 Group Field Names 2-4 

2.2.3.3 COMPUTED BY Fields 2-6 

2.2.3.4 Query Names 2-6 

2.2.3.5 Qualified Field Names 2-6 

2.2.4 Variables 2-7 

2.2.4.1 Global Variables 2-8 

2.2.4.2 Local Variables 2-8 



V 



2.2.5 DATE Value Expressions 2-9 

2.2.6 Prompting Value Expressions 2-10 

2.2.7 Values From a Table 2-11 

2.2.8 Statistical Expressions 2-11 

2.2.9 Arithmetic Expressions 2-14 

2.2.10 Concatenated Expressions 2-15 

2.3 Boolean Expressions 2-16 

2.3.1 Relational Operators 2-17 

2.3.2 Boolean Operators 2-20 

2.3.3 Compound Boolean Expressions 2-21 

3 The Record Selection Expression (RSE) 

3.1 Introduction 3-1 

3.2 Format of an RSE 3-1 

3.3 Specifying the Record Source 3-2 

3.4 Specifying Record Stream Characteristics 3-4 

3.4.1 Restricting the Number of Records 3-4 

3.4.2 Naming a Record Stream 3-6 

3.4.3 Specifying Conditions for the Record Stream 3-6 

3.4.4 Sorting the Records .3-7 

4 Record Definitions 

4.1 Introduction 4-1 

4.2 Components of a Record Definition 4-1 

4.3 Types of Fields 4-2 

4.3.1 Field Levels 4-2 

4.3.2 Level Numbers 4-3 

4.4 Field Names 4-3 

4.4.1 QUERY_NAME and QUERY_HEADER Clauses 4-4 

4.4.2 FILLER Field Name 4-4 

4.5 Field Classes 4-6 

4.6 Field Definition Clauses 4-7 

5 Commands, Statements, and Definition Clauses 

5.1 Introduction 5-1 

5.2 : (Invoke Procedure) 5-10 

5.3 @ (Invoke Command File) Command 5-13 

5.4 ABORT Statement 5-15 

5.5 ADT Command 5-19 

5.6 ALLOCATION Clause 5-20 

5.7 Assignment Statement 5-23 

5.7.1 Assigning a Value to an Elementary Field 5-23 

5.7.2 Assigning a Value to a Group Field 5-25 

5.7.3 Assigning a Value to a Variable 5-27 



vi 



5.8 BEGIN-END Statement 5-31 

5.9 CLOSE Command 5-35 

5.10 COMPUTED BY Clause 5-36 

5.11 DECLARE Statement 5-38 

5.12 DECLARE PORT Statement 5-41 

5.13 DEFINE DICTIONARY Command 5-43 

5.14 DEFINE DOMAIN Command 5-45 

5.14.1 Defining an RMS Domain 5-45 

5.14.2 Defining a View Domain 5-47 

5.15 DEFINE FILE Command 5-50 

5.16 DEFINE PORT Command 5-55 

5.17 DEFINE PROCEDURE Command. . . 5-57 

5.18 DEFINE RECORD Command 5-60 

5.19 DEFINE TABLE Command 5-63 

5.20 DEFINEP Command 5-66 

5.21 DELETE Command 5-69 

5.22 DELETEP Command 5-71 

5.23 DISPLAY Statement 5-73 

5.24 DROP Statement 5-75 

5.25 EDIT Command 5-80 

5.25.1 DELETE Command 5-86 

5.25.2 EXIT Command 5-88 

5.25.3 INSERT Command 5-90 

5.25.4 QUIT Command 5-93 

5.25.5 REPLACE Command 5-94 

5.25.6 SUBSTITUTE Command 5-96 

5.25.7 TYPE Command 5-98 

5.26 EDIT_STRING Clause 5-101 

5.26.1 Formatting Alphanumeric Fields 5-104 

5.26.2 Formatting Numeric Fields 5-107 

5.27 ERASE Statement 5-114 

5.28 EXIT Command 5-116 

5.29 EXTRACT Command 5-117 

5.30 FIND Statement 5-121 

5.31 FINISH Command 5-123 

5.32 FOR Statement 5-126 

5.33 HELP Command 5-130 

5.34 IF-THEN-ELSE Statement 5-133 

5.35 MODIFY Statement 5-136 

5.36 OCCURS Clause 5-148 

5.36.1 Fixed Number of Occurrences 5-148 

5.36.2 Variable Number of Occurrences 5-150 

5.37 OPEN Command 5-152 

5.38 PICTURE Clause 5-155 

5.39 PRINT Statement 5-158 

5.40 QUERY_HEADER Clause 5-166 

5.41 QUERY_NAME Clause 5-168 

5.42 READY Command 5-169 

5.43 REDEFINES Clause 5-175 

5.44 RELEASE Command 5-177 



vii 



5.45 REPEAT Statement 5-180 

5.46 REPORT Statement 5-183 

5.46.1 AT BOTTOM Statement (Report Writer) 5-186 

5.46.2 AT TOP statement (Report Writer) 5-188 

5.46.3 END_REPORT Statement (Report Writer) 5-191 

5.46.4 PRINT Statement (Report Writer) 5-192 

5.46.5 SET Statement (Report writer) 5-194 

5.47 SELECT Statement 5-197 

5.48 SET Command 5-202 

5.49 SHOW Command 5-206 

5.50 SHOWP Command 5-209 

5.51 SIGN Clause 5-211 

5.52 SORT Statement 5-213 

5.53 STORE Statement 5-215 

5.54 SUM Statement 5-223 

5.55 THEN Statement 5-226 

5.56 USAGE Clause 5-228 

5.57 VALID IF Clause 5-231 

5.58 WHILE Statement 5-233 



Appendixes 
A DATATRIEVE-11 Keywords 

B ASCII Values for Printing Characters 

C Syntax Formats for DATATRIEVE-1 1 



C.l DATATRIEVE Commands. C-l 

C.2 DATATRIEVE Statements C-6 

C.3 Record Definition Clauses C-ll 

C.4 Miscellaneous Syntax C-12 

Index 
Figures 

4-1 The YACHT Record Definition 4-2 

Tables 

2-1 Values Derived with Statistical Functions 2-11 

2-2 Arithmetic Operators 2-14 

2-3 Relational Operators Preceded by Field Name 2-17 

2-4 Compound Boolean Expressions 2-21 

4-1 Field Classes and Content 4-6 

4- 2 Summary of Field Definition Clauses 4-8 

5- 1 Alphabetical Summary of Commands, Statements, and Clauses 5-3 



viii 



5-2 Summary of Commands, Statements, and Clauses by Function 5-6 

5-3 Default Values for KEY fields 5-51 

5-4 Allowed Combinations of Key Field Attributes 5-52 

5-5 Access Control Privilege Codes 5-67 

5-6 Summary of DATATRIEVE Editor Commands 5-81 

5-7 Range Specifications for Editing Commands 5-83 

5-8 Edit String Characters 5-102 

5-9 Modifying the Selected Record 5-139 

5-10 Modifying All Records in the CURRENT Collection 5-140 

5-11 Modifying All Records in a Record Stream 5-141 

5-12 Modifying Each Record in a Record Stream 5-142 

5-13 Picture String Characters 5-156 

5-14 Print List Elements 5-160 

5-15 Print List Modifiers 5-161 

5-16 Access Options 5-170 

5-17 Access Modes 5-170 

5-18 Access Modes Required by DATATRIEVE Statements 5-172 

5-19 Summary of Report Writer Statements 5-184 

5-20 Report Writer AT BOTTOM Statement: Summary Elements 5-187 

5-21 Report Writer AT TOP Statement: Header and Summary Elements 5-189 

5-22 Report Writer Print List Elements 5-193 

5-23 Report Writer Print List Modifiers 5-193 

5-24 Report Writer SET Statement Arguments 5-196 

B-l ASCII Codes B-l 



ix 



How to Use This Manual 



Use this manual to find reference information on DATATRIEVE-11 terms, con- 
cepts, syntax elements, commands, statements, and clauses. 

Intended Audience 

This manual assumes that you have prior experience with DATATRIEVE-11, are 
familiar with your operating system, and understand the basic concepts of data 
processing. 

Structure 

This manual 
Chapter 1 

Chapter 2 
Chapter 3 
Chapter 4 
Chapter 5 

Appendix A 
Appendix B 
Appendix C 



contains five chapters and three appendixes: 

Presents the basic terms, concepts, and components of 
DATATRIEVE-11 

Describes DATATRIE VE value expressions and Boolean expressions 

Describes the record selection expression 

Describes field and record definition clauses 

Describes, in alphabetical order, all DATATRIEVE-11 commands, 
statements, and definition clauses 

Lists DATATRIEVE-11 keywords 

Lists ASCII values for printing characters 

Summarizes DATATRIEVE-11 syntax formats 



Related Manuals 



For more information about the subjects discussed in this book, consult the follow- 
ing manuals in the DATATRIEVE-11 documentation set: 

DA TA TRIEVE-1 1 Introduction 

DATATRIEVE-11 User's Guide 

DATATRIEVE-11 Guide to Writing Reports 

DATATRIEVE-11 Call Interface 

DATATRIEVE-11 Installation Guide/Release Notes 



Examples of DATATRIEVE commands and statements are printed in a dot matrix 
typeface. The DATATRIEVE or VAX/VMS output lines displayed on your terminal 
are printed in black. The commands and statements you enter from your terminal 
are printed in red. 

Symbols and conventions used in syntax formats: 



UPPERCASE WORDS Uppercase words in syntax formats are DATATRIEVE 



Conventions 



keywords. 



lowercase words 



Lowercase words in syntax formats indicate entries you 
must provide. 



{} 



Braces in syntax formats mean you must choose one, but 
no more than one, of the enclosed entries. 



[ ] 



Brackets in syntax formats mean you have the option of 
choosing one, but no more than one, of the enclosed 
entries. 



A horizontal ellipsis in syntax formats means you have 
the option of repeating the preceding element. 
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1.1 Introduction 

DATATRIEVE simplifies the tasks of defining, managing, and retrieving data. 
This manual is the primary source for information on the structure of this lan- 
guage. This chapter presents the basic concepts and terms of DATATRIEVE and 
describes the components of DATATRIEVE- 1 1 . 

1 .2 Starting and Ending a DATATRIEVE Session 

When you run DATATRIEVE-11, you are running an interactive program that 
accepts input from the terminal and uses the terminal as the default output 
device. 

To start a DATATRIEVE session, begin at the operating system command level 
and type DTR, RUN $DTR, or the symbol defined for DATATRIEVE-11 at instal- 
lation. DATATRIEVE displays a startup banner that indicates you have success- 
fully invoked DATATRIEVE. Note that the startup banner should look like this, 
except for the date: 

DATATRIEVE- 1 1 » Query and Report System 
Version V3.00 01-SEP-83 
Type HELP for help 
DTR > 

If you do not get this startup banner when you invoke DATATRIEVE, consult 
the person responsible for DATATRIEVE-11 at your site. 

To end your DATATRIEVE session and return to your system prompt, type EXIT 
and press RETURN or type CTRL/Z. 
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1 .3 Commands and Statements 



During an interactive DATATRIE VE session, you control DATATRIEVE by 
entering a series of commands and statements. Although intermingled in this 
manual, commands and statements have different functions and structures. 

Commands deal with the data dictionary and perform the data description func- 
tions of DATATRIEVE. Commands let you define DATATRIE VE's basic data 
structures such as domains, records, files, tables, and procedures. DATATRIEVE 
stores this information in your current data dictionary and you can assign appro- 
priate access privileges to different users. With commands, you can: 

• Create, change, and display definitions in the data dictionary (DEFINE, EDIT, 
DELETE, EXTRACT, SHOW) 

• Maintain the access control lists (ACL) associated with those definitions 
(DEFINEP, DELETEP, SHOWP) 

• Get access to domains (READY) 

• Release access to domains, variables, collections, and DATATRIEVE tables 
(RELEASE, FINISH) 

• Get on-line information about DATATRIEVE (HELP) 

• End your DATATRIEVE sessions (EXIT) 

Statements deal with data and perform the query, report, and data manipulation 
functions of DATATRIEVE. Statements let you manage data by storing, modify- 
ing, and erasing records. You also use statements to retrieve and display selected 
data. With statements, you can: 

• Store records (STORE) 

• Form and manipulate groups of records (FIND, SORT, SELECT, DROP) 

• Display data (PRINT, LIST, REPORT, SUM) 

• Modify records (MODIFY) 

• Erase records (ERASE) 

• Declare variables (DECLARE) 

• Assign values to fields and variables (Assignment) 

Commands and statements differ in structure, as well as in function. A command 
consists of a keyword (the command name, such as READY or SHOW), and may 
include other elements, such as additional keywords, dictionary names, and defi- 
nition clauses. You can enter commands only at DATATRIEVE command level, 
which is indicated by the DTR> prompt. You cannot join commands with state- 
ments or other commands to form compound commands. 
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A statement also consists of a keyword (the statement name, such as FIND or 
PRINT), and may include other elements, such as additional keywords, record 
selection expressions, value expressions, and Boolean expressions. Only state- 
ments may contain DATATRIE VE value expressions (see Chapter 2) and record 
selection expressions (see Chapter 3). Unlike commands, you can combine state- 
ments to form compound statements (BEGIN-END and THEN), complex logical 
structures (FOR, REPEAT, and WHILE), conditional transfers (IF-THEN-ELSE 
and ABORT), and procedures. 

A compound statement is two or more statements combined in a 
BEGIN-END or THEN statement. You can use a compound statement anywhere 
you can use a simple statement. DATATRIEVE executes each statement of a 
compound statement in consecutive order. 

You can perform complex or repetitive tasks by nesting statements within other 
statements. To create repeating loops, for example, nest statements in REPEAT, 
FOR, and WHILE statements. For example: 

DTR > SET NO PROMPT© 
DTR > REPEAT 3© 

C0N> PRINT "This is a test"© 

This is a test 
This is a test 
This is a test 

DTR > 

To perform conditional transfers or branching, nest statements in the 
IF-THEN-ELSE statement. For example: 

DTR > SET NO PROMPT© 
DTR> READY YACHTS WRITE© 

DTR > FOR YACHTS WITH BUILDER = "PEARSON "© 



CON> BEGIN© 

CON> PRINT© 

CON> PRINT SKIP© 

CON> IF *,"Y to modify price, N to skip" CONT "Y"© 

CON> THEN© 

CON> BEGIN© 

CON> MODIFY PRICE© 

CON> PRINT SKIP© 

CON> END ELSE© 

CON> PRINT "No change" » SKIP© 

CON> IF *."Y to continue" NOT CONT "Y" THEN© 

CON> ABORT "End of price changes"© 

CON> END© 



(continued on next page) 
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MANUFACTURER MODEL RIG 
PEARSON lOM SLOOP 33 



LENGTH 
OVER 

ALL WEIGHT BEAM PRICE 



12*441 11 



Enter Y to modify price* N to s K i p : N(reT) 
No change 



Enter Y to continue* N to quit: |\|(ret) 
ABORT: End of price changes 

Execution terminated by "ABORT" statement 
DTR > 



Chapter 5 describes all DATATRIEVE language elements in alphabetical order. 
You can find alphabetical and functional summaries of DATATRIEVE com- 
mands and statements in Tables 5-1 and 5-2. 



1 .3.1 The DATATRIEVE Character Set 



The DATATRIEVE character set consists of uppercase letters (A through Z), 
lowercase letters (a through z), digits (0 through 9), and the following special 
characters: 



+ 

/ 

## 



(period) 
(comma) 
(semicolon) 
(colon) 

(left parenthesis) 
(right parenthesis) 
(left bracket) 
(right bracket) 
(plus sign) 

(hyphen or minus sign) 

(asterisk) 

(slash) 

(space) 

(TAB) 



% 
? 



(single quotation mark) 
(equal sign) 
(vertical line) 
(less-than-sign) 
(greater-than-sign) 
(dollar sign) 
(exclamation point) 
(underscore) 
(percent sign) 
(question mark) 
(at sign) 
(RETURN) 

(double quotation mark) 



DATATRIEVE accepts lowercase letters as input, but converts them to upper- 
case letters before analyzing the syntax of the input. DATATRIEVE preserves 
lowercase letters only in character string literals enclosed in quotation marks. 

Similarly, DATATRIEVE accepts hyphens (-) as input but converts them to 
underscores (_) before analyzing the syntax of your input. To use a hyphen as a 
minus sign in an expression such as PRICE - PRICE * 01 > include spaces on both 
sides of if. If you do not include spaces, DATATRIEVE converts the hyphen to an 
underscore and tells you that the field "PRICE -PRICE" is undefined or used out 
of context. You do not have to put spaces on both sides of the hyphen in a numeric 
expression such as 10-2*0.1, although it is a good idea to do so for readability and 
consistency. 
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1 .3.2 Command and Statement Elements 



Every DATATRIEVE command and statement consists of the command or state- 
ment name and one or more of the following elements: 

• Other keywords 

• Names, which identify items associated with values 

• Expressions, which specify values or create record streams 

• Continuation characters, which allow a command or statement to be continued 
on the next input line 

• Terminator, which signals the end of a command or statement 

• Comments, which allow you to enter text with a command or statement 

The following sections describe all these elements except expressions. Chapter 2 
discusses DATATRIEVE value expressions and Boolean expressions and 
Chapter 3 discusses the record selection expression (RSE). 

1 .3.2.1 Keywords — A keyword is an element of a command or statement. 
Most keywords are command or statement names, but some keywords are used in 
record definitions and dictionary tables. In this manual, DATATRIEVE key- 
words appear in uppercase letters. 

You can use keywords where shown in syntax formats of commands and state- 
ments. Do not use keywords as names of domains, records, fields, dictionary 
tables, collections, procedures, variables or views. Appendix A contains a list of 
all DATATRIEVE keywords. 

1.3.2.2 Names — A DATATRIEVE name is a character string used to identify 
the following items: 

Collections Fields Procedures 

Dictionary tables Ports Variables 

Domains Records Views 

A DATATRIEVE name can consist of 1 through 31 letters, digits, hyphens (-), 
and underscores (_) and must conform to the following rules: 

• A name must begin with a letter. 

• A name must end with a letter or digit. 

• A name cannot be a keyword. (See Appendix A for a list of DATATRIEVE 
keywords.) 
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You can continue a name from one line to another by typing a hyphen (-) and 
pressing RETURN. 

Some valid DATATRIEVE names are: 

• TOTAL_SALARY 

• YACHTS 

• PRICE_PER_POUND 

• YE AR_TO_DATE_E ARNINGS_FOR_ 1980 
Some invalid DATATRIEVE names are: 

• TOTAL (Duplicates a keyword) 

• 1980_EARNINGS (Does not begin with a letter) 

• PRICE_PER_POUND($/LB) (Contains illegal characters) 

• YEAR_TO_DATE_EARNINGS_FOR_FY_1980 (Too many characters) 

1.3.2.3 Termination and Continuation Characters — DATATRIEVE uses spe- 
cial characters to terminate commands and statements and to continue com- 
mands and statements that are longer than one line. 

A terminator signals the end of a command or statement. The formal terminator 
in DATATRIEVE is the semicolon (;). You can use a semicolon to separate com- 
mands and statements on the same input line. For example: 

DTR> READY FAMILIES? FIND FAMILIES WITH NUMBER_K I DS = 25 SELECT 1 (ret) 
C 6 records found] 

DATATRIEVE does not begin processing the commands and statements on an 
input line until you press RETURN. 

You can end most commands and statements (except the DEFINE and DELETE 
commands and the DECLARE statement) by pressing RETURN when the syntax 
of the command or statement is complete. If SET PROMPT is in effect and you 
press RETURN before a statement or command is complete, DATATRIEVE 
prompts you for the next element. 

You can use the hyphen (-) at the end of an input line to continue your command 
or statement on the next line. DATATRIEVE does not check the syntax of your 
input until you press RETURN at the end of a line that does not end with a 
hyphen. The total number of characters in an input line extended by hyphens 
cannot exceed 132 or DATATRIEVE displays an error message. 

If a line you are extending ends with a complete word, precede the hyphen with a 
space. Otherwise, DATATRIEVE treats the characters at the end of one line and 
the beginning of the next as a single character string. If you have to change lines 
in the middle of a character string literal, name, or keyword, do not precede the 
hyphen with a space. 
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Note that DATATRIE VE does not convert a hyphen at the end of a line to an 
underscore. For example: 



RW> END -(ret) 
C0N> REPORT© 

Invalid report statement ( "ENDREPORT" ) 
This example is valid: 

RW> END- -(ret) 
RW> REPORT© 

1 .3.2.4 Comments — You can include a comment in an input line by preced- 
ing the comment with an exclamation point (!) and ending it by pressing 
RETURN. The comment can include any characters on your terminal keyboard, 
except escape and control characters. 

You can use comments in procedures and command files to document their func- 
tions. DATATRIEVE stores comments in the dictionary as part of the procedure 
definition, but ignores the comments when you invoke the procedure or execute 
the command file. 



Most DATATRIEVE applications involve sequences of commands and state- 
ments that you use regularly. You can avoid retyping such a sequence by storing 
it in the data dictionary as a procedure. With the DEFINE PROCEDURE com- 
mand, you give the procedure a name and enter both the name and the sequence 
of commands and statements into the dictionary. For example: 

DTR > DEFINE PROCEDURE SUM_YACHTS© 
DFN> READY YACHTS© 

DFN> FIND FIRST *."How many to find" YACHTS© 

DFN> SUM 1 ( "NUMBER "/"OF YACHTS") USING 9 »© 

DFN> PRICE USING $$$$»$$$ BY BUILDER© 

DFN> END_ PROCEDURE© 

DTR > SHOW PROCEDURES© 

Procedures: 



When you want to use the sequence of commands and statements in a procedure, 
invoke the procedure by entering a colon (:) and the procedure name. 
DATATRIEVE then executes the statements and commands in the procedure. 
For example: 

DTR > :SUM_YACHTS© 

Enter How in a n y to f i n d : G© 



1 .3.3 DATATRIEVE Procedures 



SUM_YACHTS 



DTR > 



NUMBER 
MANUFACTURER OF YACHTS 



PRICE 



NUMBER 
OF YACHTS 



PRICE 



ALBERG 
ALB I N 
AMERICAN 



3 



$3G ,951 
$64 »000 
$28 »790 



S 



$129 ,741 



DTR> 
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1.4 DATATRIEVE Prompts 

Three types of DATATRIEVE prompts help you keep track of your status during 
a DATATRIEVE session: 

• Input line prompts show that DATATRIEVE is ready for your input. 

• Syntax prompts show what DATATRIEVE expects your next input to be. 

• Prompts for storing and modifying values request you to enter values for fields 
in records. 

1.4.1 Input Line Prompts 

DATATRIEVE has six input line prompts: 

• DTR> is the DATATRIEVE command level prompt. It shows that 
DATATRIEVE is ready for you to enter a DATATRIEVE command or state- 
ment. 

• CON> is the continuation prompt. DATATRIEVE displays the CON> prompt 
when you press RETURN before completing a command or statement. You 
must finish the command or statement or enter a CTRL/Z to return to 
DATATRIEVE command level. 

• DFN> is the definition prompt. DATATRIEVE displays the DFN> prompt 
after you enter a DEFINE command and continues to prompt with DFN> 
until you end the DEFINE command or enter CTRL/Z. 

• QED> is the DATATRIEVE-1 1 Editor command mode prompt. 
DATATRIEVE displays the QED> prompt after you enter an EDIT command. 
You can then enter Editor commands to modify dictionary objects. To exit from 
the Editor, type CTRL/Z in response to the QED> prompt. 

• IN> is the DATATRIEVE-1 1 Editor insert mode prompt. DATATRIEVE dis- 
plays the IN> prompt after you enter an INSERT or REPLACE editing com- 
mand in response to the QED> Editor command mode prompt. See Sections 
5.25.3 and 5.25.5 for information on the INSERT and REPLACE editing com- 
mands. 

• RW> is the Report Writer prompt. DATATRIEVE displays the RW> prompt 
after you enter a REPORT statement and continues to prompt with RW> until 
you end the report or enter CTRL/Z. 

The CON> prompt is the most complex DATATRIEVE prompt. Because com- 
mands and statements have so many options, you may press RETURN, intending 
to continue the command or statement, and find that DATATRIEVE executes 
what you have entered. That is because DATATRIEVE interprets what you have 
entered as a complete command or statement. If you intend to continue the com- 
mand or statement, press RETURN after a comma, in the middle of a string of 
required keywords, or in the middle of a value expression or Boolean expression. 
You can also use the hyphen (-) as a continuation character. See Section 1.3.2.3 
for more information on the hyphen. 
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1 .4.2 Syntax Prompts 



When you press RETURN before completing a command or statement, 
DATATRIE VE prompts you with a phrase in square brackets that tells you what 
sort of input it expects: 

DTR > READY© 

[Looking for Dictionary Element] 
C0N> YACHTS© 
DTR> FIND© 

[Looking for "FIRST"* domain name* or collection name] 

C0N> YACHTS WITH© 

[Looking for Boolean expression] 

C0N> LOA© 

[Look in 3 for relational operator ( e <=i t it i etc.)] 
C0N> GT© 

[Looking for a value expression] 
C0N> 24© 

C 1 5 records found] 
DTR > 



DATATRIEVE displays these prompting messages by default. You can suppress 
syntax prompts by entering a SET NO PROMPT command at DATATRIEVE 
command level. To enable syntax prompts again, enter the SET PROMPT com- 
mand. 



1 .4.3 Prompts for Storing and Modifying Values 

When you enter STORE or MODIFY statements that do not contain the USING 
clause, DATATRIEVE prompts you to enter the values for the fields to be stored 
or modified. These prompts take the general form "Enter" followed by a field 
name: 



D T R > READY FAMILIES WRITE© 
DTR > STORE FAMILIES© 
Enter FATHER: GEORGE© 
Enter MOTHER: MARTHA© 
Enter NUMBER-K IDS: l© 
Enter K I D-NAME : JENNIFER© 
Enter AGE: 12 
DTR > 



The SET NO PROMPT command does not affect these prompts. 

Data Files and DATATRIEVE Record Definitions 



DATATRIEVE stores information in data files. A data file contains a group of 
related records. A record contains data organized by and stored in fields. The two 
types of fields are elementary fields and group fields: 

• An elementary field contains one item of data. This item can consist of one 
character ("1") or a number of characters that are to be interpreted as a unit 
("10 Downing Street"). 

• A group field contains one or more elementary fields and may also contain 
other group fields. 
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You control the storage and interpretation of information with the DEFINE 
RECORD command. When you define a record, you define the fields of the record 
and specify how DATATRIEVE stores and retrieves data in the record. 

You also specify how records are stored in the data file. The data file that con- 
tains your records has certain attributes that depend on the way you define the 
record fields. An individual record contains unique information, but all the 
records in a data file share a common organization as specified in the record 
definition. 

To define the physical organization of a data file, use the DEFINE FILE com- 
mand. DATATRIEVE data files are RMS files and can be organized in two ways: 

• A sequential file contains records stored physically next to each other. The 
sequence of records in the file is completely independent of the information in 
any field of the record. Each new record in a sequential file is stored at the end 
of the last record written to the file. Thus, you can modify records in a sequen- 
tial file but you cannot delete records. 

• An indexed file contains records stored by index field values. When you define 
the file with the DEFINE FILE command, you can specify one field in the 
record, called the primary key, to be used as the index for the file organization. 
Records are stored in the file according to the order of values in the primary 
key field. The primary key for a personnel file, for example, might be the 
employee number. Because records are stored by index rather than by 
sequence, you can delete records from an indexed file. You cannot, however, 
modify the value of the primary key field. 

DATATRIEVE does not support RSTS/E stream files. 

See Chapter 4 in this manual for more information on DATATRIEVE records 
and record definitions. 

1 .6 DATATRIEVE Domains 

To manipulate and manage data in a file, you must explicitly connect that data 
file to a record definition. DATATRIEVE makes this connection with a data 
structure called a domain. You use the DEFINE DOMAIN command to write a 
domain definition and to store that definition in a data dictionary. 

A domain definition establishes a name for the domain and associates that name 
with the names of a record definition and a data file. When you use the name of a 
domain, you tell DATATRIEVE to use a particular record definition to interpret 
the data stored in a specific file. 

1 .7 ADT, the Application Design Tool 

ADT, the Application Design Tool, is an interactive feature of DATATRIEVE- 11 
that helps you define a domain, a record, and a data file. 

ADT uses your responses to a series of questions to build a command file contain- 
ing the DATATRIEVE commands to define the domain, record, and data file. 
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When you invoke the command file, DATATRIEVE executes each command, 
stores the definitions of the domain and record in your current dictionary, and 
creates an RMS file. 

Chapter 3 in Introduction to DATATRIEVE -11 discusses the use of the 
Application Design Tool and contains a sample ADT session. 

1.8 DATATRIEVE Tables 

A DATATRIEVE table is a group of code and description pairs you create and 
store as a named table. With DATATRIEVE tables, you associate codes with 
translations, thereby saving record space and time. A code like "EB", for exam- 
ple, can be associated with a lengthy translation like "Employee Benefits". You 
can then store the code in a record, and print the descriptive character string 
associated with the code in the table. Because the code can be as short as a single 
character and its associated description much longer, tables can save a great deal 
of record space. Tables can also help you validate data according to the presence 
or absence of a data item in the table. 

To create and name a table, use the DEFINE TABLE command. DATATRIEVE 
stores the table definition in the data dictionary. See the section in this manual 
on the DEFINE TABLE command and Chapter 13 of the DATA TRIEVE- 11 
User's Guide for more information on defining and using tables. 

1 .9 The DATATRIEVE-1 1 Report Writer 

The DATATRIEVE-1 1 Report Writer helps you display your data in easy-to-read 
formats. You can display a report on your terminal, print it on a hard-copy 
printer, or store it in an RMS file for display or printing at a later time. 

With the Report Writer, you can specify the number of lines per page or the num- 
ber of pages in your report. You can also create title pages and print special head- 
ings above and detail lines below groups of sorted data that share a common 
value in one or more fields. Your reports can have the title, page number, and 
date at the top of each page and can report statistical summaries of your data in 
columns and at the bottoms of the report, individual pages, or groups of sorted 
data. The Report Writer supplies default formatting values for elements such as 
columns-per-page that you do not supply. For more information, see the 
DA TA TRIEVE -1 1 Guide to Writing Reports. 

1 .1 The DATATRIEVE-1 1 Editor 

With the DATATRIEVE Editor, you can modify and add to data dictionary 
objects already defined in your current data dictionary. The Editor has an edit 
mode and an insert mode: 

• When you invoke the Editor with the EDIT command, DATATRIEVE 
responds with the QED> edit mode prompt. In edit mode, the Editor interprets 
all of your input as commands and you can display and alter the text of the dic- 
tionary object. Use CTRL/Z to return to DATATRIEVE command level. 
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• When you enter the INSERT or REPLACE command in response to the QED> 
prompt, DATATRIEVE displays the IN> insert mode prompt. In insert mode, 
the Editor interprets all of your input as new text to be entered into the diction- 
ary object. Use CTRL/Z to return to edit mode. 

See the section on the EDIT command in this manual and Chapter 17 in the 
DATATRIEVE-11 User's Guide for information on edit mode commands. 

1.11 The DATATRIEVE-1 1 Remote Access Interface 

The DATATRIEVE-11 Remote Access Interface allows you to call 
DATATRIEVE on your own system or on another DECnet node from an applica- 
tion program. It also allows you to run DATATRIEVE from a remote terminal. 
The Remote Access Interface consists of: 

• The DATATRIEVE-11 Distributed Server 

• The DATATRIEVE-11 Call Interface 

• The DATATRIEVE-11 Remote Terminal Interface 

The Distributed Server, also called DDMF (Distributed Data Manipulation 
Facility), is a "slave" program that allows users on other DECnet nodes to use 
DATATRIEVE for accessing data files and dictionaries on your node. A 
DATATRIEVE component sends commands to DDMF, and DDMF passes the 
results back to that component. Call Interface subroutines, for example, send 
commands to and receive information from a distributed server. DDMF can per- 
form all of the DATATRIEVE functions with the exception of ADT and Guide 
Mode. 

Both DATATRIEVE-11 and VAX-11 DATATRIEVE have distributed servers. 

The Call Interface allows application programs to access data files and data dic- 
tionaries by calling DATATRIEVE subroutines. With the Call Interface, you can 
customize the appearance of DATATRIEVE, write programs to perform tasks 
that interactive DATATRIEVE cannot do, and access data through 
DATATRIEVE on other DECnet nodes. To use the Call Interface, include calls to 
external DATATRIEVE subroutines in your program. The subroutines pass 
information between the calling programs and a local or remote DATATRIEVE 
Distributed Server. You must have DECnet software to use the Call Interface. 

The DATATRIEVE Remote Terminal Interface (REMDTR) allows you to access 
the DATATRIEVE Remote Call Interface from a terminal. The Terminal 
Interface uses the Remote Call Interface to establish a DECnet link to the 
Distributed Server. When the link is established, REMDTR displays the version 
of DATATRIEVE and the REMDTR> prompt. From this point on, you can type 
commands and statements as though you are running interactive DATATRIEVE 
on the remote node. 

See the DATATRIEVE-11 Call Interface Manual for information on using the 
Remote Terminal Interface and on writing programs that use the Call Interface. 
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Value Expressions and Boolean Expressions 




2.1 Introduction 

This chapter describes the value expressions and Boolean expressions you can 
use in D ATATRIE VE- 1 1 statements. 

A value expression is a string of symbols that specifies a value for D ATATRIE VE 
to use when executing statements. A Boolean expression is the logical represen- 
tation of a relationship between value expressions. The value of a Boolean 
expression is either true or false. 

2.2 Value Expressions 

Value expressions specify values for D ATATRIE VE to use when executing state- 
ments. DATATRIEVE-11 provides you with the following types of value expres- 
sions: 

• Character string literals 

• Numeric literals 

• Fieldnames 

• Global and local variables 

• Date value expressions 

• Prompting value expressions 

• Values from dictionary tables 

• Statistical expressions 

• Arithmetic expressions including parentheses 

• Concatenated expressions 
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The following sections describe these value expressions. 
2.2.1 Character String Literals 

A character string literal is a string of printing characters up to 130 characters 
long. The maximum size for an input line in DATATRIEVE-11 is 132 characters. 
In character string literals, however, two of those characters are used for opening 
and closing quotation marks. Printing characters consist of uppercase and lower- 
case letters, numbers, and the following special characters: 

!@#$%A&*()-_ = +<[ 

{]}-;:'" \ !,<.>/? 

You can continue a literal on more than one line by typing a hyphen (-), the 
DATATRIEVE continuation character, and pressing RETURN. DATATRIEVE 
strips the hyphen from that part of the character string literal and waits for you 
to complete the literal by typing the closing quotation mark on the next line. As 
long as the total number of characters (including two double quotation marks) in 
the literal does not exceed 132, you can use any number of continuation charac- 
ters between the quotation marks. 

You can create a character string exceeding 132 characters in two ways: 

• Use concatenated expressions (described in Section 2.2.9). 

• Define a very long group field comprised of several elementary fields, each of 
which can be up to 132 characters long, then store character string values in 
each elementary field. The following record definition, for example, can store a 
string literal of 468 characters: 

01 STRING LIT* 

05 LINE_1 PIC )•(( 132) . 

05 LINE_2 PIC K( 132) . 

05 LINE_3 PIC )•(( 132) . 

05 LINE_4 PIC X(80) • 

Use double quotation marks to enclose character string literals: 

Literal: "maximum price is $iaoo. please re-enter price." 
Value: maximum price is *iaoo. please re-enter price. 

To include double quotation marks in a character string literal, you must type 
two consecutive quotation marks for every one you want to include in the literal: 

Literal: "They s a i d > ""We're 3 o i n 3 

Value: They said* "We're Soina." 
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Although DATATRIEVE usually converts all lowercase letters of your input to 
uppercase, it preserves lowercase letters in character string literals. Preserving 
the case of character string literals has important effects on comparisons using 
character string literals, because such comparisons are case-sensitive: 

DTR > READY YACHTS© 

DTR> FIND YACHTS NITH BUILDER = "ALB I N "(ret) 
C3 records found] 

DTR> FIND YACHTS WITH BUILDER = "alb in"© 
CO records found] 
DTR > 

2.2.2 Numeric Literals 

A numeric literal is a string of digits that DATATRIEVE interprets as a decimal 
number. A numeric literal may contain a decimal point and up to 18 digits. The 
decimal point is optional and does not count as a digit. 

A numeric literal cannot begin or end with a decimal point. For example, .5 and 
123. are not valid numeric literals, but 0.5 and 123.0 are valid. 

With two restrictions, the data type of a field or variable determines the maxi- 
mum numeric literal you can assign to the field or variable: 

• You cannot specify more than 18 digits in the PICTURE (PIC) clause. If you do, 
DATATRIEVE displays an error message on your terminal. 

• The format specified in the PICTURE (PIC) clause of a field or variable also 
limits the values you can assign with numeric literals. See the section on the 
PICTURE clause in Chapter 5 for a discussion of these restrictions. 

2.2.3 Field Names 

You can use these types of field names as value expressions: 

• Elementary and REDEFINES field names 

• Group field names 

• Virtual field names (COMPUTED BY fields) 

• Query names 

• Qualified field names 

2.2.3.1 Elementary and REDEFINES Field Names — The value specified by 
an elementary field name is the value stored in a field of a record. 

If the field name you use refers to a REDEFINES field, the value associated with 
the name is determined by the clauses that define the REDEFINES field in the 
record definition. In the following example, PART_NUMBER is an elementary 
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field, and PART_NUMBER_PARTS and PART. NUMBER. GROUPS are 
REDEFINES fields that redefine the PART_NUMBER field. The PRINT state- 
ment shows how DATATRIE VE interprets values stored in the 
PART_NUMBER elementary field when you specify the elementary field name 
and the REDEFINES field names: 

DTR> SET NO PROMPT© 
DTR> SHOW PART-REC(RET) 
RECORD PART-REC 
01 PART-RECORD . 

05 PART-NAME PIC )<( 10) ♦ 

05 PART-NUMBER PIC 9(10) ♦ 

05 PART_NUMBER_ PARTS REDEFINES PART-NUMBER, 

07 PRODUCT-GROUP PIC 99. 

07 PRODUCT- YEAR PIC 99, 

07 ASSEMBLY-CODE PIC 9. 

07 SUP_ASSEMBLY PIC 9(5), 
05 PART_NUMBER_GROUPS REDEFINES PART-NUMBER, 

07 PRODUCT_GROUP_ID PIC 9(4). 

07 PART-DETA I L_ I D PIC 9(6). 

DTR> READY PARTS® 

DTR> FOR PARTS PRINT PART-RECORD » PART - NUMBER - PARTS > PART - NUMBER - GROU PS© 

PRODUCT PART 



PART 


PART 


PRODUCT 


PRODUCT 


ASSEMBLY 


SUP 


GROUP 


DETAIL 


NAME 


NUMBER 


GROUP 


YEAR 


CODE 


ASSEMBLY 


ID 


ID 


DODADS 


1 1 13335559 


1 1 


13 


3 


35559 


1 113 


335559 


GOFER 


09S7B54321 


09 


87 


B 


54321 


0987 


S54321 


WALLTHING 


5555599999 


55 


55 


5 


99999 


5555 


599999 


WIDGET 


12345B7S90 


12 


34 


5 


S7890 


.1234 


5S7890 



D T R > 



2.2.3.2 Group Field Names — When you use group field names in assignment 
statements, the value of the group field depends on the type of assignment. The 
usual assignment statement has this format: 

group-field-name-1 = group-field-name-2 

In this type of statement, DATATRIE VE assigns values on the basis of similar 
elementary field names. The value of group field name 2 includes the values of all 
elementary fields, all REDEFINES fields, and all COMPUTED BY fields. 

DATATRIE VE assigns the values of elementary fields in group field 2 to the ele- 
mentary fields in group field 1 that match group field 2 names. 

DATATRIEVE ignores fields in group field 2 whose names do not match any field 
names in group field 1. If an elementary field name in group field 1 does not 
match a group field 2 field name, DATATRIEVE assigns the following values: 

• Zero (numeric fields) 

• Blank (alphabetic or alphanumeric fields) 

DATATRIEVE stores no values in any COMPUTED BY or REDEFINES fields in 
group field 1, regardless of any matches between the names of those fields and 
fields in group field 2. The values of the elementary, REDEFINES, and 
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COMPUTED BY fields associated with group field name 2 are the values stored 
in or associated with the fields that constitute group field 2 of a record. 

Because of problems that can arise from conflicting data types, assignments of 
the following type are not recommended: 

elementary-field-name = group-field-name 

If you make an assignment of this type, the value of the group field is the same as 
the value displayed on your terminal with a DISPLAY group field name state- 
ment. The value is the concatenation of the values in the elementary fields that 
constitute the group field. DATATRIEVE ignores REDEFINES and 
COMPUTED BY fields. You can reduce conflicts of data types by using an alpha- 
numeric PICTURE string in the definition of the elementary field. The following 
example illustrates the results of assigning the value of the group field SPECS, 
which contains both alphanumeric and numeric elementary fields, to an elemen- 
tary field with an alphanumeric PICTURE string and a numeric PICTURE 
string: 

DTR> SET NO PROMPT© 
DJR> SHOW STRING_REC© 
RECORD STR I NG-REC 

USING 
01 TOP ♦ 

03 ELEM-F I ELD PIC X( 18) ♦ 

DXR> SHOW NUMER I C_REC© 
RECORD NUMER I C_REC 

USING 
01 TOP ♦ 

03 ELEM-F I ELD PIC EH IS) ♦ 

D J R > SH0W YACHT© 
RECORD YACHT 

USING 
01 BOAT ♦ 
03 TYPE* 

OS MANUFACTURER PIC X<10) 
QUERY-NAME IS BUILDER* 
OS MODEL PIC X< 10) . 
03 SPECIFICATIONS 

QUERY-NAME SPECS* 
OS RIG PIC X(S) 

VALID IF RIG EQ "SLOOP" ♦"KETCH" ♦"MS" » " Y A W L " ♦ 
OG LENGTH-OVER-ALL PIC XXX 

VALID IF LOA BETWEEN 15 AND 50 
QUERY-NAME IS LOA* 
OS DISPLACEMENT PIC 99933 
QUERY-HEADER IS "WEIGHT" 
EDIT-STRING IS ZZ >ZZ9 
QUERY-NAME IS DISP* 
OS BEAM PIC 99. 
OG PRICE PIC 99999 

VALID IF PRICE>DISP*1 *3 OR PRICE EQ 
EDIT-STRING IS $$$*$$$* 

DTR> READY YACHTS READ© 
DTR> ! dD 

DTR > ! Print the SPECS a roup field for the first yacht© 
DTR> !© 

D T R > PRINT SPECS OF FIRST 1 YACHTS© , x . 

(continued on next page) 
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LENGTH 
OVER 

RIG ALL WEIGHT BEAM PRICE 

KETCH 37 20*000 12 *3G»951 

DTR > READY STRING-TEST WRITE© 
DTR> READY NUMERIC-TEST WRITE© 

DTR> \m 

DTR> ! Store the SPECS Maine in the alphanumeric© 

DTR > ! elementary field* then print STR I NG_TEST(rD 

DTR> \m 

DTR> FOR FIRST 1 YACHTS © 

CON> STORE STRING-TEST USING ELEM-F I ELD = SPECS© 

DTR > PRINT STRING-TEST© 

ELEM 
FIELD 

KETCH 37 20000123G 

DTR> !© 

DTR> ! Store the SPECS Maine in the numeric© 
DTR> ! elementary field* then print NUMERIC-TEST© 
DTR > !© 

DTR> FOR FIRST 1 YACHTS© 

CON> STORE NUMERIC-TEST USING ELEM-F I ELD = SPECS© 

Non-disfit in strinsf "KETCH 37 200001236951"* isnorintf character(s) 

DTR > PRINT NUMERIC-TEST© 

ELEM 
FIELD 

0372 1 2 3 G 3 5 1 

DTR > 

2.2.3.3 COMPUTED BY Fields - COMPUTED BY fields are virtual fields. 
DATATRIEVE does not store the value of a COMPUTED BY field in a record. 
That value is calculated every time you refer explicitly or implicitly to a 
COMPUTED BY field. The value specified by a virtual field name is the value 
associated with that field name in a record. 



2.2.3.4 Query Names — If the record definition contains a query name for a 
field, you can use the query name exactly as you use the associated field name. 



2.2.3.5 Qualified Field Names — To clarify the context for recognizing names 
and associating values with those names, you can qualify field names with sev- 
eral optional elements: 

• Context variables allow you to distinguish between fields in different record 
streams. 

• Record names allow you to distinguish between fields in different domains 
that have the same field name. 

• Group field names allow you to distinguish between fields that have the same 
field name, but are contained in different group fields. 
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Use the following format to qualify field names: 
[context-variable][record-name][group-field-name].. .[field-name] 

To refer to fields within a record, you must create a context. If there is more than 
one valid context for a field name, DATATRIEVE uses the most recent valid con- 
text. If there is no valid context for a field name, DATATRIEVE issues an error 
message: 

DTR > SET NO PROMPT© 
DTR > READY YACHTS© 

DTR> FIND TINIES IN YACHTS WITH LOA LE 25© 
C13 records found] 

DTR > FIND BIGGIES IN YACHTS WITH LOA GE 40© 

C 8 records found] 

DTR > FOR A IN BIGGIES© 

C0N> PRINT TINIES WITH BUILDER = A ♦ BU I LDER© 

LENGTH 
OVER 



MANUFACTURER 


MODEL 


RIG 


ALL 


WEIGHT 


BEAM 


PRICE 


ISLANDER 


BAHAMA 


SLOOP 


24 


4 »200 


08 


$6 >500 


DTR > PRINT© 














No record selected* printing whole collection 












LENGTH 














OVER 








MANUFACTURER 


MODEL 


RIG 


ALL 


WEIGHT 


BEAM 


PRICE 


CHALLENGER 


41 


KETCH 


41 


2G f 700 


13 


$51 »228 


COLUMBIA 


41 


SLOOP 


41 


20 >700 


1 1 


$48 ,490 


GULFSTAR 


41 


KETCH 


41 


22 »000 


12 


$41 »350 


ISLANDER 


FREEPORT 


KETCH 


41 


22 »000 


13 


$54 »970 


NAUTOR 


SWAN 41 


SLOOP 


41 


17 *750 


12 




NEWPORT 


41 S 


SLOOP 


41 


18 »000 


1 1 




OLYMPIC 


ADVENTURE 


KETCH 


42 


24 ,250 


13 


$80 ,500 


PEARSON 


419 


KETCH 


42 


21 t 


13 




DTR > PRINT A© 












Field "A" is 


u n d e f i n e d 


or used 


out of 


context 







DTR> 

This example uses three context variables: BIGGIES, TINIES, and A. BIGGIES 
and TINIES also become the collection names. The FOR statement uses the con- 
text variable A to establish a context for the first PRINT statement. The next 
PRINT statement does not specify a context, so DATATRIEVE uses the most 
recent context and displays all the records in the most recently formed collection, 
BIGGIES. An attempt to display the variable A without a context causes 
DATATRIEVE to display an error message. 



2.2.4 Variables 

With the DECLARE statement, you can define global and local variables and use 
them as value expressions. When you declare them, DATATRIEVE initializes 
numeric variables to zero and alphanumeric variables to a space. 
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2.2.4.1 Global Variables — You define global variables with DECLARE state- 
ments entered at DATATRIEVE command level. That is, any variable not 
declared in a BEGIN-END block is a global variable. You can then use a global 
variable as a value expression in any DATATRIEVE statement. Unless you 
define a global variable with a COMPUTED BY clause, the global variable 
retains the value you assign to it until you either assign it a new value or release 
it with the RELEASE command. 

The value of a global variable defined with a COMPUTED BY clause depends on 
the value expression that controls the computation. The following example 
declares the COMPUTED BY variable to be 1.2 times the price of a boat in the 
YACHTS domain. The value of the variable changes according to the value of the 
PRICE field for different records: 

DTR> SET NO PROMPT© 

DTR> READY YACHTS© 

DTR> DECLARE MAR COMPUTED BY PRICE * 1,2,© 

DTR > FOR FIRST 5 YACHTS PRINT PRICE* MAR USING $$$,$$$. 99© 

PRICE MAR 

$38,951 $44 ,341 .ZD 

$17 f900 $21 ,480.00 

$27*500 $33 , 000 ♦ 00 

$18,800 $22,320.00 

$ 9 ,895 $1 1 ,874.00 

DTR > 



2.2.4.2 Local Variables — You can define local variables with DECLARE 
statements entered in BEGIN-END and THEN statements. A local variable 
stays in effect for subsequent statements of the compound statement in which it 
is declared, but has no meaning in any outer statements containing that com- 
pound statement. A local variable is released as soon as DATATRIEVE com- 
pletes the execution of the clause or statement in which it was declared: 

DTR > SET NO PROMPT© 
DTR > BEGIN© 

C0N> DECLARE X PIC XXX.© 

C0N> >< = "TOP"© 

C0N> PRINT X© 

C0N> BEGIN© 

C0N> DECLARE X PIC 9.99.© 

C0N> X = 1.23© 

C0N> PRINT X© 

C0N> END© 

C0N> PRINT X© 

C0N> END© 



TOP 



1 .23 



TOP 
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(continued on next page) 



DTR> PRINT )<m 

Field " X " is u ndefined or used out of context 
DTR > 

In this example, the variable X declared in the inner BEGIN statement does not 
affect the variable X declared in the outer BEGIN statement, even though the 
inner X has a different data type and value. Neither local variable exists when 
DATATRIE VE completes the execution of the compound statements containing 
them. 

Note 

To avoid problems resolving names for variables and fields, do not 
use variable names that duplicate field names of domains you have 
readied. 



2.2.5 DATE Value Expressions 

To define a field as a date, use the USAGE IS DATE clause. The IS keyword is 
optional. You can then assign the current system date to the field with the 
DATATRIE VE date value expression, "TODAY": 

DTR > DECLARE X USAGE DATE ♦ (ret) 
DTR> X = "TODAY " (ret) 
DTR> PRINT )<m 



iS-Mav-83 
DTR > 

To use date value expressions, assign the DATE data type to the field or variable. 
Otherwise, DATATRIE VE treats the expression as a character string literal: 

DTR > PRINT "TODAY " (ret) 
TODAY 

DTR> 

DATATRIE VE returns the character string literal "TODAY" because the quoted 
expression is not associated with a variable or field of the DATE data type. 
However, if you supply an edit string containing date edit string characters, 
DATATRIE VE returns the current system date in the form specified by the edit 
string: 

DTR > PRINT "TODAY " USING DD-MMM- YY(ret) 
18-May-83 

dtr:> 

You can also subtract one date from another to find the elapsed number of days. 
You might, for example, want to know how many days you have to complete a 
project. Define variables for today's date and the project due date, then subtract 
today's date from the project due date. 
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DTR > DECLARE T USAGE DATE ♦ (ret) 
DTR > T = "TODAY "(ret) 

DTR > DECLARE PROJECT-DUE USAGE DATE ♦ (ret) 
DTR > PROJECT-DUE = "21 - AUG -83 "(ret) 
DTR> PRINT (PROJECT-DUE - T ) (ret) 
31 

DTR > 

DATATRIEVE indicates that the project is due in 31 days. 
2.2.6 Prompting Value Expressions 

If you want DATATRIEVE to prompt you for a value, use a prompting value 
expression. This feature is especially useful in a procedure because it allows you 
to use a different value each time you invoke the procedure. DATATRIEVE rec- 
ognizes two types of prompting expressions: 

*. prompt-string 

**. prompt-string 

The prompt string is a character string literal. If the prompt string contains no 
blanks and conforms to the rules for DATATRIEVE names, you do not have to 
enclose the literal in quotation marks. Otherwise, you must enclose it in quota- 
tion marks. 

If you put a *. prompt value expression in a REPEAT loop or a FOR loop, 
DATATRIEVE prompts you for a value each time it executes the loop. 

If you put a **. prompt value expression in a REPEAT loop or a FOR loop, 
DATATRIEVE prompts you for a value only once, the first time it executes the 
loop. If the **.prompt value expression assigns a value to a variable or a field, 
DATATRIEVE uses the same value each time through the loop. This feature is 
especially useful when storing or modifying a group of records that have a com- 
mon value in one or more fields. 

The following example shows the difference between the *.prompt and **.prompt 
value expressions: 



DTR> 


SET NO PROMPT© 


DTR > 


READY OWNERS WRITE© 


DTR> 


REPEAT 2 (ret) 


CON> 


STORE OWNERS USING© 


CON> 


BEGIN© 


C0N> 


NAME = * . NAME© 


CON> 


BOAT-NAME = * * BOAT_NAME© 


CON> 


BUILDER = **♦ BUILDER© 


CON> 


MODEL = ***MODEL© 


CON> 


END© 


Enter 


NAME: KAREN© 


Enter 


BOAT-NAME: SEASICK© 


En t e r 


BUILDER: BEAN© 


En t e r 


MODEL: 12© 


Enter 


NAME: ANDREW© 


Enter 


BOAT-NAME: DINGHY-2© 


DTR> 
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The first time DATATRIEVE executes the BEGIN statement, it prompts for all 
four values. The second time, it only prompts for the *.NAME and 
*. BOAT_ NAME values and uses the values previously entered for MODEL and 
BUILDER for the second record. 

2.2.7 Values From a Table 

You can use a value stored in a dictionary table anywhere the syntax of a 
DATATRIEVE statement allows a value expression. The format for retrieving a 
value from a dictionary table is: 

value-expression VIA table-name 

Dictionary table entries are stored as code string/translation string pairs. If the 
specified value expression is stored as a code string in the specified table, the 
value of the entire expression is the corresponding translation string in the table. 

If the table contains an ELSE clause and the value expression you specify does 
not match any code string in the table, the value of the entire expression is the 
translation string stored in the ELSE clause of the table. If the table contains no 
ELSE clause and the value expression you specify does not match any code string 
in the table, DATATRIEVE tells you the value was not found. 

See Chapter 13 of the DATATRIEVE -11 User's Guide for more information 
about creating and using dictionary tables. 

2.2.8 Statistical Expressions 

Statistical expressions consist of DATATRIEVE statistical function keywords 
(MAX, MIN, AVERAGE, TOTAL, and COUNT) and value expressions. 

Table 2-1 lists DATATRIEVE statistical functions and the values they return. 



Table 2-1 : Values Derived with Statistical Functions 



Function 


Value Returned 


AVERAGE 


The average value of the value expression 


COUNT 


The number of records in the CURRENT collection or 
in a specified collection or record stream 


MAX 


The largest value of the value expression 


MIN 


The smallest value of the value expression 


TOTAL 


The total value of the value expression 



You can use statistical expressions anywhere a DATATRIEVE statement allows 
a value expression. A statistical expression can itself be the value expression of 
another statistical expression. With the exception of TOTAL, DATATRIEVE 
uses the edit string specified in the EDIT_STRING clause of a field definition 
when printing a statistical value for a field. 
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With the exception of the COUNT function, you must supply a value expression 
when using statistical functions. Use this format for all statistical functions 
except COUNT: 

function-name value-expression [OF rse] 

A value expression is usually a field name or the name of a variable that the sta- 
tistical function operates on: 

DTR> SET NO PROMPT© 
DTR> READY YACHTS© 

DTR> PRINT MAX PRICE OF FIRST 10 YACHTS© 

PRICE 
$38 ,951 
DTR> 

When the value expression is more complex than a field name or variable name, 
enclose the expression in parentheses to avoid unexpected results: 

DTR > READY YACHTS© 

DTR> FIND A IN YACHTS WITH BUILDER = "ALB IN" AND PRICE NE 0© 
C 3 records found] 
DTR > PRINT ALL© 

LENGTH 









OVER 






MANUFACTURER 


MODEL 


RIG 


ALL 


WEIGHT 


BEAM PRICE 


ALB I N 


79 


SLOOP 


26 


4 >200 


10 $17*90 


ALB I N 


BALLAD 


SLOOP 


30 


7 >27S 


10 $27*50 


ALB I N 


UEGA 


SLOOP 


*? ~j 


5 >070 


08 $18 >G0 



DTR > ! PRINT THE AVERAGE PRICE PER POUND WITHOUT PARENTHESES© 
DTR > !© 

DTR> PRINT AVERAGE PRICE/DISP OF A© 
5,079 

2 ,932 
4,207 

DTR > ! PRINT THE AVERAGE PRICE PER POUND WITH PARENTHESES© 
DTR > !© 

DTR > PRINT AVERAGE (PRICE / DISP) OF A© 

3 , 903 

DTR> 

When DATATRIEVE executes the PRINT statement without parentheses 
around the expression, it divides the average PRICE by 4200 (the weight of the 
first yacht in the collection), then by 7276 (the weight of the second yacht in the 
collection), and then by 5070 (the weight of the third yacht) to give three unex- 
pected, but accurate, values of 5.079, 2.932, and 4.207. The second PRINT state- 
ment yields the expected results, the average of 5.079, 2.932, and 4.207. 
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The COUNT function does not need a value expression, so use this format: 
COUNT [OF rse] 

Note the use of a record selection expression in the following: 

D T R > SET NO PROMPT© 
DTR> READY FAMILIES© 

DTR> PRINT COUNT OF FAMILIES WITH NUMBER_K IDS EO 2© 
G 

When you supply a record selection expression in a statistical expression, 
DATATRIEVE uses all the records in the resulting record stream to compute the 
value returned by the function: 

DTR> PRINT AUERAGE PRICE OF YACHTS WITH BUILDER = "AMERICAN"© 

PRICE 
$14 >395 
DTR> 

If you do not specify an RSE, DATATRIE VE uses all records in the CURRENT 
collection to compute the value returned by the function. DATATRIEVE displays 
the message "A current collection has not been established" if you do not specify 
an RSE and have no CURRENT collection. 

When you use two or more statistical expressions in the same statement, be sure 
to specify an RSE in each expression to identify the record stream on which the 
function is to operate. If you do not, your results may be misleading. Because no 
RSE was specified for the AVERAGE function in the following example, 
DATATRIEVE displays the average LOA for the whole current collection. The 
RSE for the AVERAGE function in the second PRINT statement tells 
DATATRIEVE to compute the average LOA for only the first five yachts, thus 
producing a different average: 

DTR > SET NO PROMPT© 
DTR> FIND YACHTS© 
CI 13 records found] 

DTR> PRINT AUERAGE LOA > TOTAL LOA OF FIRST 5 YACHTS© 

LENGTH LENGTH 
OVER OVER 
ALL ALL 

30. UG 

DTR> PRINT AVERAGE LOA OF FIRST 5 YACHTS >© 
C0N> TOTAL LOA OF FIRST 5 YACHTS© 

LENGTH LENGTH 
OVER OVER 
ALL ALL 

29 14G 

DTR> 
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2.2.9 Arithmetic Expressions 



An arithmetic expression consists of value expressions and arithmetic operators. 
The value expressions must evaluate to numbers. You can use an arithmetic 
expression anywhere the syntax of a DATATRIE VE statement allows a value 
expression. 

DATATRIEVE provides four arithmetic operators. Table 2-2 shows these arith- 
metic operators and the operation each performs. 



Table 2-2: Arithmetic Operators 



Operator 


Operation 


+ 


Addition 




Subtraction or negation 


* 


Multiplication 


/ 


Division 



You do not have to use spaces to separate arithmetic operators from value expres- 
sions, except in one case: if a field or variable name precedes a minus sign, you 
must put a space between the minus sign and the field or variable name. 
Otherwise, DATATRIEVE interprets the minus sign as a hyphen and converts it 
to an underscore: 



DTR> 


DECLARE 


X PIC 99 ,m 




DTR > 


x = em 






DTR > 


!© 






DTR > 


! Print 


X - 1 w i t h o u t 


a space before the minus s i 4 n (ret) 


DTR> 


!© 




DTR > 


PRINT X- 


1© 




" F i e 1 


d X_l" i 


s u n define d 


or used out of context 


DTR > 


!© 






DTR > 


! Print 


X - 1 with a 


space before the minus s i S n (ret) 


DTR > 


!©) 




DTR > 
7 


PRINT X 


-1© 




DTR > 


!© 






DTR > 


! Print 


1 - X w i t h o u t 


a space before the minus s i 3 n (ret) 


DTR > 


!© 




DTR > 


PRINT 1- 







-7 
DTR > 

You can control the order in which DATATRIEVE performs arithmetic oper- 
ations by using parentheses. DATATRIEVE follows these rules of precedence 
when evaluating arithmetic expressions: 

1. DATATRIEVE first evaluates any value expressions in parentheses. 

2. DATATRIEVE performs multiplications and divisions from left to right in 
the arithmetic expression. 



2-14 Value Expressions and Boolean Expressions 



3. DATATRIEVE performs additions and subtractions from left to right in the 
arithmetic expression. 

The following examples show how parentheses affect the evaluation of arith- 
metic expressions: 

DTR > PRINT (6 * 7) + 5(ret) 
47 

DTR> PRINT G * (7 + 5)© 
72 

DTR > PRINT 12 - G / 2© 
9 ♦ 

D T R > PRINT (12 - G) / 2(H) 
3*000 

DTR> 

2.2.10 Concatenated Expressions 

DATATRIEVE allows you to join expressions with character values to form a 
concatenated expression. You can use a concatenated expression anywhere the 
syntax of a DATATRIEVE statement allows a character string literal. When 
DATATRIEVE concatenates value expressions, it converts their values to char- 
acter string literals. 

DATATRIEVE provides two ways to concatenate expressions: a single or dou- 
ble bar separating value expressions. In each case, DATATRIEVE first con- 
verts the value expression to its character string literal, then joins the literals 
to form a longer literal. Both operators treat leading spaces in the second lit- 
eral as spaces. The type of operator determines how DATATRIEVE treats 
trailing spaces in the first literal. 

When you use the single bar ( I ), DATATRIEVE treats trailing spaces in the first 
string literal as spaces: 

Expression: "ABC"!"DEF" "abc. "! m def" "abc"!" def" "abc "!" def" 
Result: abcdef abc def abc def abc def 

The double bar causes DATATRIEVE to suppress trailing spaces in the first 
literal: 

Expression: "abc"I!"def m "abc "ii'-def" "abc !!" def" "abc " i s " def 
Result: abcdef abcdef abc def abc def 

Concatenated expressions provide the only method for assigning values to fields 
or variables whose lengths exceed 256 characters. For example: 

DTR > DECLARE GTR PIC X(300) EDIT.STRING IS T(50),(ret) 
DTR> STR = *.Ll!*.L2i*.L3i*«L4i*.L5(lD 

Enter LI: This strins contains the first part of a Ion 3 character (ret) 
Enter L 2 : string. This string is so Ions that you can't use Just (ret) 
Enter L3: one character string literal to assign a value to it* (ret) 
Enter L 4 : You need concatenated expressions to increase the length (ret) 
Enter L5: of this string beyond the limit of 132 c h a r a c t e r s . (ret) 

(continued on next page) 
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DTR> PRINT STR© 



STR 

This strins contains the first part of a Ions 
character string* This string is so lonS that you 
can't use Just one character string literal to 
assign a value to i t ♦ You need concatenated 
expressions to increase the length of this string 
beyond the limit of 132 characters. 

DTR> 

This example combines the T edit string indicating that a line of text can contain 
50 characters, prompting value expressions, and character string literals to 
assign a value to a long variable. You can use similar assignment statements in 
the USING clauses of the STORE and MODIFY statements. Note that you must 
type a space before pressing RETURN. The T edit string prints up to 50 charac- 
ters on a line, but does not break up words from one input line to another unless 
you type a space to separate the last word on a line from the first word on the next 
line. 

If you want to format the printed output of a concatenated expression, you must 
specify an edit string for it. DATATRIE VE does not use any edit strings specified 
for the components of a concatenated expression when you print it. 

Note 

The length of concatenated expressions is limited only by the amount 
of DATATRIEVE pool space available. However, concatenated 
expressions are not intended for storing massive amounts of text. If 
DATATRIEVE pool space is exhausted, DATATRIEVE will stop 
executing the statement it is currently processing. 



2.3 Boolean Expressions 

A Boolean expression is the logical representation of a relationship between 
value expressions. The value of a Boolean expression is either true or false. The 
Boolean expressions you can use in DATATRIEVE-11 consist of value expres- 
sions, relational operators, and Boolean operators. Relational operators control 
the comparison of value expressions. Boolean operators enable you to join two or 
more Boolean expressions and to reverse the value of a Boolean expression. All 
Boolean expressions contain value expressions and relational operators, and 
some contain Boolean operators. 

You can use Boolean expressions in the following DATATRIEVE clauses and 
statements: 

• The WITH clause in a record selection expression 

• The IF clause of an IF-THEN-ELSE statement 

• The VALID IF clause in a record definition 

• The WHILE statement 
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2.3.1 Relational Operators 



With relational operators, you can compare value expressions, check whether a 
code string is contained in a table, and check whether a record stream is empty or 
not. Most Boolean expressions contain a field name, a relational operator, and a 
value expression. Table 2-3 shows the format for using each relational operator 
preceded by a field name. 

Table 2-3: Relational Operators Preceded by Field Name 



Boolean Expression Formats and Evaluations 



field-name \ EQ > {val-exp} [,...] 
( EQUAL) 

True if the value of field name is equal to a value expression in the list. 



field-name NOT EQUAL {val-exp} [,...] 

True if the value of field name is not equal to any value expression in the list. 



field-name < NOT-EQUAL \ val-exp 
( NOT_ EQUAL) 

True if the value of field name is not equal to the value expression. 



field-name ) GT ( val-exp 

GREATER-THAN 
GREATER_THAN 

True if the value of field name is greater than the value expression. 



QE 

field-name < GREATER-EQUAL > val-exp 
( GREATER- EQUAL) 

True if the value of field name is greater than or equal to the value expression. 



field-name ) LT { val-exp 

LESS-THAN 
LESS_THAN 

True if the value of field name is less than the value expression. 



field-name \ LESS-EQUAL \ val-exp 
( LESS_ EQUAL) 

True if the value of field name is less than or equal to the value expression. 



field-name ( BT ) val-exp- 1 [AND] val-exp-2 

( BETWEEN > 

True if the value of field name is between value expression 1 and value expression 2. Value 
expression 1 must be less than value expression 2. 



(continued on next page) 
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Table 2-3: Relational Operators Preceded by Field Name (Cont.) 



Boolean Expression Formats and Evaluations 

field-name (NOTBT \ val-exp-1 [AND] val-exp-2 

\ NOT BETWEEN/ 

True if the value of field name is not between value expression 1 and value expression 2. Value 
expression 1 must be less than value expression 2. 

field-name fCONT I val-exp 

(CONTAINING/ 

True if the value of field name contains the value expression as a substring. 

field-name /NOT CONT ) val-exp 
(NOT CONTAINING/ 

True if the value of field name does not contain the value expression as a substring. 

field-name IN table-name 

True if the value of field name is a code string in table name. 

field-name NOT IN table-name 

True if the value of field name is not a code table name. 



ANY rse 

True if the record stream is not empty. 



Note that you can specify more than one value expression only after the = , EQ, 
EQUAL, and NOT EQUAL operators. DATATRIEVE displays an error message 
if you specify more than one value expression after any other operator: 

DTR> SET NO PROMPT© 
DTR> READY YACHTS© 

DTR> FIND A IN YACHTS WITH BEAM EQ 9» 10 » 11© 
C 7 records found] 

DTR > FIND B IN YACHTS WITH BEAM NE 12 t 13, 14© 
Expected end of s t a t e m e n t t encountered " » " 
DTR > 

In a Boolean expression, you can also use a prompting value expression or a vari- 
able name in place of a field name. You cannot, however, use any other value 
expressions in place of the field name. Generally, you use relational operators to 
compare field values to value expressions. 

The order and value associated with numeric and alphanumeric characters is 
determined by the ASCII collating sequence. Appendix B lists printing ASCII 
characters and their corresponding values. Because lowercase letters have a 
higher ASCII value than uppercase letters, DATATRIEVE treats lowercase let- 
ters in character string literals as greater than uppercase letters. 

In Boolean expressions using the CONTAINING relational operator, the com- 
parison of the value expression and the field value is not case-sensitive. That is, 
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uppercase letters and lowercase letters are treated the same, whether or not you 
enclose a character string literal in quotation marks. 

The following examples show the use of relational operators to compare field val- 
ues to value expressions: 



DTR> SET NO PROMPT© 
DTR> READY YACHTS© 

DTR > FIND YACHTS WITH BEAM EO 9* 10* 14© 
C 5 records found] 

DTR > PRINT CURRENT WITH RIG NE "SLOOP "(ret) 

LENGTH 









OVER 










MANUFACTURER 


MODEL 


RIG 


ALL 


WEIGHT 


BEAM 


PRICE 


EASTWARD 


HO 


MS 


24 


7 


»000 


09 


*15 *900 


FISHER 


30 


KETCH 


30 


14 


♦ 500 


09 




GRAMPIAN 


34 


KETCH 


33 


12 


1 


10 


$29 ,675 



DTR > PRINT COUNT OF YACHTS WITH BUILDER CONTAINING "EE"© 

DTR > FIND YACHTS WITH LOA < 20© 
C 2 records found] 

DTR > FIND YACHTS WITH PRICE BETWEEN 7000 AND 10000© 
C 2 records found] 
DTR > 

The IN relational operator compares the contents of a field with the code strings 
in a dictionary table. This comparison is useful for validating data you assign to 
fields or variables. You can, for example, write a record definition that uses a 
table to validate the data before it is stored: 

dtr::= 

DFN> 
DFN> 
DFN> 
DFN> 
DFN> 
DFN> 
DFN > 
DTR > 



The relational operator ANY checks whether a record stream is empty. This 
operator is useful for work with lists in hierarchical records. The record selection 
expression following ANY generally specifies the name of a list or sublist: 

DTR > SET NO PROMPT© 
DTR > READY FAMILIES© 

DTR > PRINT FAMILIES WITH ANY KIDS WITH AGE = 20© 

NUMBER KID 
FATHER MOTHER KIDS NAME AGE 

BASIL MERIDETH 6 BEAU 

BROOKS 
ROBIN 
JAY 
WREN 

(continued on next page) 
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DEFINE RECORD PH0NE_REC USING© 
01 PHONE,© 

02 NAME PIC X(20) .© 

02 NUMBER PIC 3(7) EDIT_STRING IS XXX-XXXX,© 
02 LOCATION PIC X<9) ♦© 
02 DEPARTMENT PIC XX© 

VALID IF DEPARTMENT IN DE PT_TABLE ♦ © 

5© 



28 
26 
24 

"7 "7 

17 



JILL 

JERDME RUTH 4 ERIC 

CISSY 
NANCY 
MICHAEL 

DTR > PRINT FAMILIES WITH ANY KIDS NITH K I D_NAME CONT "RAL"© 

NUMBER KID 
FATHER MOTHER KIDS NAME AGE 

JIM ANN 2 URSULA 7 

RALPH 3 

DTR > 



For more information on lists and hierarchies, see Chapter 15 of the 
DA TA TRIEVE-1 1 User's Guide. 



20 
32 
24 
? ? 

20 



2.3.2 Boolean Operators 

DATATRIE VE recognizes four Boolean operators: AND, OR, BUT, and NOT. 
With AND, OR, and BUT, you can join two or more Boolean expressions together 
to form a single Boolean expression. NOT allows you to reverse the value of a 
Boolean expression. 

When you link Boolean expressions with AND or BUT, the resulting expression 
is true only if all the Boolean expressions linked with AND or BUT are true. 
When you link Boolean expressions with OR, the resulting expression is true if 
any one of the Booleans linked with OR is true. When you precede a Boolean 
expression with NOT, the resulting expression is true if the Boolean expression 
following NOT is false: 

DTR > SET NO PROMPT© 
DTR> READY YACHTS© 

DTR > PRINT YACHTS WITH BUILDER = "PEARSON" AND LOA = 30© 

LENGTH 
OVER 

MANUFACTURER MODEL RIG ALL WEIGHT BEAM PRICE 

PEARSON 30 SLOOP 30 8 »320 09 

DTR > FIND YACHTS WITH BUILDER = "PEARSON" OR LOA = 30© 
C 2 1 records found] 

DTR> PRINT FAMILIES WITH FATHER NOT EQ "JIM" AND© 
C0N> ANY KIDS WITH AGE GT 31© 

NUMBER KID 



FATHER 


MOTHER 


KIDS 


NAME 


AGE 


JEROME 


RUTH 


4 


ERIC 


32 








CISSY 


24 








NANCY 


*? ? 








MICHAEL 


20 


HAROLD 


SARAH 


3 


CHARLIE 


31 








HAROLD 


35 








SARAH 


27 



DTR > 



2-20 Value Expressions and Boolean Expressions 



2.3.3 Compound Boolean Expressions 

Use parentheses to group Boolean expressions into compound Boolean 
expressions: 

DTR> SET NO PROMPT© 

DTR> PRINT YACHTS WITH© 

CON> (MODEL = "28" AND BUILDER = "TANZER") OR© 

CON> (MODEL = "BALLAD " AND BUILDER = " ALB I N " ) © 

LENGTH 
OVER 

MANUFACTURER MODEL RIG ALL WEIGHT BEAM PRICE 

ALB I N BALLAD SLOOP 30 7,276 10 *27 »500 

TANZER 28 SLOOP 28 G ,800 10 $17*500 

DTR > 

DATATRIEVE evaluates Boolean expressions in parentheses before evaluating 
other Boolean expressions. If a Boolean expression contains Boolean operators as 
well as parentheses, DATATRIEVE evaluates the compound expression in the 
following order: 

1 . Expressions enclosed in parentheses 

2. Expressions preceded by NOT 

3. Expressions combined with AND 

4. Expressions combined with OR 

Table 2-4 shows how DATATRIEVE evaluates compound Boolean expressions. 

Table 2-4: Compound Boolean Expressions 



Expressions and Evaluations 



bool-1 AND bool-2 AND bool-3 

True if all three Boolean expressions are true 



bool-1 AND (bool-2 OR bool-3) 

True if Boolean 1 is true and either Boolean 2 or Boolean 3 is true 



(bool-1 AND bool-2) OR bool-3 

True if Boolean 1 and Boolean 2 are true or if Boolean 3 is true 



(bool-1 AND bool-2) OR (bool-3 AND bool-4) 

True if both Boolean 1 and Boolean 2 are true or if both Boolean 3 and Boolean 4 are true 



NOT (bool-1 OR bool-2) AND bool-3 

True if both Boolean 1 and Boolean 2 are false and Boolean 3 is true 
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The Record Selection Expression (RSE) 



3.1 Introduction 

This chapter describes how to use the DATATRIEVE-11 record selection expres- 
sion (RSE) to form record streams and collections. In the RSE, you specify the 
conditions that DATATRIEVE uses to form subsets and combinations of records 
that you can output, report, and change. When you use RSEs to specify records, 
DATATRIEVE operations execute faster than when you use collections to specify 
records; see Chapter 18 in the DATATRIEVE-11 User's Guide for information on 
optimizing your DATATRIEVE applications and using RSEs and collections. 

The group of records that satisfies the conditions you specify in the RSE is called 
a record stream. 



3.2 Format of an RSE 



The format of a record selection expression as it applies to records in RMS- 11 files 
is: 



Format 



I" FIRST n 
L ALL 



[context-var IN] 



domain-name 
collection-time 
list-name 



[WITH boolean-expression] 
[SORTED BY sort-key [,...]] 



This format shows that the RSE contains one required element: the source of 
records as specified by the domain, collection, or list name. There are also four 
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optional elements that affect the characteristics of the record stream. The follow- 
ing sections describe each element of an RSE. 

3.3 Specifying the Record Source 

The name of the record source is the only required element in a record selection 
expression. The record source tells DATATRIEVE which domain, collection, or 
list to search when forming a record stream. 

You can use the given name of any type of DATATRIEVE domain as a record 
source for DATATRIEVE to search when forming a record stream. Before you 
can use a domain name in an RSE, you must ready the domain with a READY 
command: 

DTR> READY YACHTS© 
DTR> PRINT YACHTS© 

LENGTH 









OYER 








MANUFACTURER 


MODEL 


RIG 


ALL 


WEIGHT 


BEAM 


PRICE 


ALBERG 


37 MK II 


KETCH 


37 


2 1 


12 


$3G »951 


ALB I N 

♦ 


79 


SLOOP 
« 


26 


a »zoo 

♦ 


10 


$17 ,900 


♦ 

WRIGHT 


SEAWIND II 


♦ 

SLOOP 


33 


« 
« 

14 ,900 


09 


$34 ,490 



DTR> 



To use a collection as the record source, you must first establish the collection 
with a FIND statement. To specify the most recently established collection, use 
the keyword CURRENT: 

DTR> READY YACHTS© 
DTR > FIND YACHTS© 
C 1 1 3 records found] 
DTR > PRINT CURRENT© 

LENGTH 









OVER 








MANUFACTURER 


MODEL 


RIG 


ALL 


WEIGHT 


BEAM 


PRICE 


ALBERG 


37 MK II 


KETCH 


37 


20 >000 


12 


$36 ,951 


ALBIN 


79 


SLOOP 


2S 


4 ,200 
♦ 


10 


$17 »900 


♦ 
» 

WRIGHT 


SEAWIND II 


« 
♦ 

SLOOP 


33 


♦ 

14 >900 


09 


$34 ,480 



DTR> 
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To form a named collection to use as the record source, specify the collection 
name: 

DTR> SET NO PROMPT© 

DTR > FIND BIG_ONES IN YACHTS NITH LOA > 40© 
C 8 records found] 

DTR> PRINT BIG_0NES WITH PRICE NE 0® 

LENGTH 









OVER 








MANUFACTURER 


MODEL 


RIG 


ALL 


WEIGHT 


BEAM 


PRICE 


CHALLENGER 


41 


KETCH 


41 


2G »700 


13 


$51 »228 


COLUMBIA 


41 


SLOOP 


41 


20 »700 


1 1 


$48 ,490 


GULFSTAR 


41 


KETCH 


41 


22 1 


12 


$41 *350 


ISLANDER 


FREEPORT 


KETCH 


41 


22 »000 


13 


$54 ,970 


OLYMPIC 


ADVENTURE 


KETCH 


42 


24 ,250 


13 


$80 ,500 



DTR> 



To retrieve, modify, or report data in the items of a list in a hierarchical domain, 
use the name of the list as the record source. By using a list name to specify the 
source of records for an RSE, you can form a record stream from the list items in a 
single record or in multiple records. In the following example, the SELECT state- 
ment picks out the first record in the current collection. Then the RSE in the 
PRINT statement identifies the first item in the KIDS list in the selected record 
as the record stream: 

DTR > READY FAMILIES© 
DTR > FIND FAMILIES© 
C14 records found] 
DTR > SELECT© 

DTR > PRINT AGE OF FIRST 1 KIDS© 
AGE 
7 

DTR> 

To form a stream of records containing lists, use the FOR statement. In the fol- 
lowing example, the FOR statement forms a record stream containing a list of 
families with 2 children. Then the RSE in the PRINT statement identifies the 
KIDS list in the record stream as the record source to search for children older 
than 20: 

DTR > SET NO PROMPT© 

DTR > FOR FAMILIES WITH NUMBER_KIDS = 2© 

C0N> PRINT KID_NAME * AGE OF KIDS WITH AGE GT 20© 

KID 

NAME AGE 

ANN 29 

JEAN 26 

MARTHA 30 

TOM 27 

DTR > 
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For more information on using the PRINT statement to display items from lists, 
see the section on the PRINT statement in this manual. Refer also to Chapter 15 
of the DATATRIEVE-11 User's Guide for additional examples illustrating the 
use of hierarchical records. 

Note that you cannot use a list name as the record source for an ERASE state- 
ment. To change or erase fields in a list, you must establish a valid record context 
with a SELECT statement or a FOR statement and use the MODIFY statement. 
The following example shows how to establish a valid record context and how to 
use CTRL/Z to abort the modification without changing the record: 

DTR > SET ND PROMPT© 

DTR> READY FAMILIES WRITE© 

DTR > SHOW FAMILY-REC© 

RECORD FAMILY-REC 

01 FAMILY ♦ 

03 PARENTS ♦ 

06 FATHER PIC X< 10) ♦ 
06 MOTHER PIC X< 10) ♦ 
03 NUMBER-KIDS PIC 39 EDIT-STRING IS Z3. 
03 KIDS OCCURS TO 10 TIMES DEPENDING ON NUMBER_K I DS ♦ 
06 EACH_KID, 

09 KID_NAME PIC X(10) QUERY-NAME IS KID. 
09 AGE PIC 99 EDIT-STRING IS ZS. 

5 

DTR > ERASE ALL OF KIDS© 

Field "KIDS" is undefined or used out of context 

DTR > MODIFY EACH-KID OF FIRST 1 KIDS© 

Field "KIDS" is undefined or used out of context 

DTR > FOR FIRST 2 FAMILIES MODIFY EACH-K I D OF KIDS© 

Enter K ID-NAME : "Z 

Execution terminated by operator 

DTR> FIND FIRST 2 FAMILIES© 

C 2 records found] 

DTR> SELECT© 

DTR > MODIFY EACH-K I D OF KIDS© 

Enter KID-NAME: "' Z 

Execution terminated by operator 

DTR> 



Specifying Record Stream Characteristics 

Once you have identified the record source, you can use the four optional ele- 
ments of the RSE to specify the characteristics of the record stream. You can use 
any or all of these optional elements in an RSE, but you must specify them in the 
order shown in the syntax diagram in Section 3.1. The following sections describe 
each optional element. 



3.4.1 Restricting the Number of Records 

The keywords FIRST and ALL allow you to specify how many records are to be in 
the record stream formed by the RSE. If you omit this element of the RSE or 
specify ALL, the record stream consists of all records that satisfy the conditions 
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of the RSE. If you specify FIRST n, where n is a value expression that evaluates 
to a positive integer, the record stream consists of n records that satisfy the condi- 
tions of the RSE: 



DTR > PRINT FIRST 3 YACHTS© 









LENGTH 
















OVER 










MANUFACTURER 


MODEL 


RIG 


ALL 


WEIGHT 


BEAM 


PRICE 


ALBERG 


37 MK II 


KETCH 


37 


20 #000 


12 


$35 


»000 


ALB I N 


79 


SLOOP 


2G 


a #200 


10 


$17 


#900 


ALBIN 


BALLAD 


SLOOP 


30 


7 #276 


10 


$27 


#500 



DTR > 



If n does not evaluate to an integer, DATATRIEVE truncates the fractional part 
of the value and uses the integer part as the value for n. When n is greater than 
the number of records satisfying the conditions of the RSE, the record stream 
consists of as many records as satisfy the conditions. For example: 

DTR> SET NO PROMPT© 

DTR > PRINT MODEL » PRICE OF FIRST 5 YACHTS WITH© 
C0N> BUILDER = "AMERICAN"© 

MODEL PRICE 
2G $9*895 
26-MS $18*895 

DTR> 

When you specify a sort order in the RSE, DATATRIEVE sorts the records as 
specified. In these examples, DATATRIEVE selects the first three records as the 
record stream: 

DTR> READY YACHTS© 

DTR > PRINT FIRST 3 YACHTS© 

LENGTH 
OVER 



MANUFACTURER 


MODEL 


RIG 


ALL 


WEIGHT 


BEAM 


PRICE 


ALBERG 


37 MK II 


KETCH 


37 


20 #000 


12 


$36 #951 


ALBIN 


79 


SLOOP 


2G 


4 #200 


10 


$17 #900 


ALBIN 


BALLAD 


SLOOP 


30 


7 #276 


10 


$27 #500 


DTR > PRINT FIRST 3 YACHTS SORTED BY LOA© 












LENGTH 














OVER 








MANUFACTURER 


MODEL 


RIG 


ALL 


WEIGHT 


BEAM 


PRICE 


WINDPOWER 


IMPULSE 


SLOOP 


16 


650 


07 


$3 #500 


CAPE DORY 


TYPHOON 


SLOOP 


19 


1 #900 


06 


$4 #295 


ENCHILADA 


20 


SLOOP 


20 


2 #300 


07 





DTR> 



The Record Selection Expression (RSE) 3-5 



3.4.2 Naming a Record Stream 



You can give a record stream a name by including a context variable in the RSE. 
Using context variables to qualify field names also lets you refer to fields from 
different record streams in the same statement. Chapter 12 of the 
DATATRIEVE-11 User's Guide provides additional information on the use of 
context variables and qualified field names. 

When you use a context variable in a FIND statement, the context variable 
becomes the name of the collection. Until you form another collection or release 
the one just formed, it has two names: the name of the context variable and 
CURRENT (because it is the most recently formed collection): 

DTR> READY YACHTS© 

DTR> FIND BIGGIES IN YACHTS WITH LOA GT 40© 

C 8 records found] 

DTR> SHOW COLLECTIONS© 

Collections: 

BIGGIES (also CURRENT) 

DTR> 

When you use nested FOR loops to join domains sharing one or more field names, 
you can use context variables in RSEs to specify which of the identically named 
fields you want DATATRIEVE to act on. The RSE in the second FOR statement 
in the following example compares all yachts to find yachts that have the same 
specifications: 

DTR> SET NO PROMPT© 
DTR > FOR A IN YACHTS© 



C0N> FOR B IN 


YACHTS WITH B.TYf 


3 E NE A, 


TYPE AND B,SPECS = i 


C0N> PRINT A ♦ 


BOAT© 














LENGTH 










OVER 




MANUFACTURER 


MODEL 


RIG 


ALL 


WEIGHT BEAM PRICE 


CARIBBEAN 


35 


SLOOP 


35 


18*000 11 $37*850 


CHRIS-CRAF 


CARIBBEAN 


SLOOP 


35 


18*000 11 $37*850 


SCAMP I 


30 


SLOOP 


30 


G*B00 10 


SOLNA CORP 


SCAMPI 


SLOOP 


30 


8 *B00 1 



DTR> 



3.4.3 Specifying Conditions for the Record Stream 

The WITH clause allows you to specify conditions for the record stream. The 
Boolean expression in the WITH clause specifies: 

• Values for DATATRIEVE to compare with values in records 

• The type of comparison for DATATRIEVE to perform when searching through 
the record source 
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Any Boolean expression is valid in a WITH clause. See Chapter 2 for information 
on forming Boolean expressions. 



When the values of a record satisfy the conditions specified in the Boolean 
expression (that is, when the Boolean expression is true), the record becomes part 
of the record stream formed by the RSE: 



DTR > SET NO 


PROMPT© 








DTR> PRINT Y 


ACHTS WITH 


BUILDER 


= "ALB 


I N "(RET) 








LENGTH 










OVER 




MANUFACTURER 


MODEL 


RIG 


ALL 


WEIGHT BEAM 


ALB I N 


79 


SLOOP 


2B 


4 » 2 1 


AJ_BIN 


BALLAD 


SLOOP 


30 


7>27B 10 


ALB I N 


VEGA 


SLOOP 


27 


5 * 7 8 



DTR> READY FAMILIES© 

DTR> FIND FAMILIES WITH ANY KIDS WITH AGE > 30© 
C 3 records found] 

DTR > PRINT CURRENT WITH ANY KIDS WITH© 
CON> KID_NAME = "ELLEN"© 



NUMBER KID 
FATHER MOTHER KIDS NAME AGE 



JIM 



LOUISE 



ANNE 

JIM 

ELLEN 

DAVID 

ROBERT 



31 
29 
2B 
24 
IB 



DTR > 



You can also use a comma to form a compound Boolean expression having an 
implied OR: 

DTR > FIND YACHTS WITH RIG = "MS"> "KETCH"© 
1 1 8 records found] 
DTR > 



3.4.4 Sorting the Records 



The SORTED BY clause lets you sort the records in the record stream. You can 
sort the records according to the values in one or more fields or according to a 
related value expression. The SORTED BY clause has this format: 

SORTED [BY] sort-key,... 

In the sort key, you can specify both the order of the sort with a D ATATRIE VE 
keyword and the field to be used as the basis of the sort. The sort-key has this 
format: 

!ASC CEND I NG ] ) 

DESCC ENDING] ( field-name [>♦♦♦] 

INCREASING ( 

DECREASING ) 
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If you do not include a keyword to specify the order of the sort with the first sort 
key, the default order is ascending. If you do not specify the sort order, 
DATATRIE VE uses the sort order that applied to the preceding field. As the for- 
mat indicates, you must include at least one field name in the sort key. 
Additional sort keys must be separated by commas. 

The keywords ASC, ASCENDING, and INCREASING are equivalent and 
specify that the sorted values begin with the smallest and end with the largest: 

DTR > READY YACHTS© 

DTR > FIND FIRST 3 YACHTS WITH PRICE NE 0© 
C3 records found] 

DTR > PRINT BUILDER * LOA > PRICE OF CURRENT SORTED BY ASC PRICE© 

LENGTH 
□ UER 

MANUFACTURER ALL PRICE 

ALB IN 2B $17 f 900 

ALBIN 30 $27*500 

ALBERG 37 $36*951 

DTR > 

The keywords DESC, DESCENDING, and DECREASING are also equivalent 
and specify that the sorted values begin with the largest and end with the 
smallest: 

DTR > PRINT BUILDER > LOA * PRICE OF CURRENT SORTED BY DESC PRICE© 

LENGTH 
OYER 

MANUFACTURER ALL PRICE 

ALBERG 37 $36*951 

ALBIN 30 $27 * 500 

ALBIN 2G $17*900 

DTR> 

The value of characters for alphanumeric sorts is determined by the ASCII val- 
ues of the characters. See Chapter 2 and Appendix B for information on the 
ASCII sorting sequence. 

When you specify multiple sort keys, DATATRIEVE treats the first field in the 
sort list as the major sort key and successive field or value expressions as^ minor 
keys: 

DTR> SET NO PROMPT© 
DTR > READY YACHTS© 

DTR> FIND YACHTS WITH LOA BT 28 AND 30© 
C 2 4 records found] 

DTR> FIND Y IN CURRENT WITH PRICE NE 0© 
£11 records found] 

DTR > PRINT BUILDER* LOA* PRICE OF Y SORTED BY© 
C0N> ASC LOA* DESC PRICE© 

(continued on next page) 
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LENGTH 





OVER 






MANUFACTURER 


ALL 


PRICE 


SABRE 


28 




> 


CAPE DORY 


28 


$21 


»990 


TANZER 


28 


$17 


»500 


ISLANDER 


28 


$15 


>908 


GRAMPIAN 


28 


$14 


>475 


NORTHERN 


29 


$20 


»975 


ALB I N 


30 


$27 


»500 


HUNTER 


30 


$21 


>500 


ISLANDER 


30 


$20 


»990 


IRWIN 


30 


$19 


»950 


GRAMPIAN 


30 


$17 


>775 



DTR > 



Chapter 3 of the DATA TRIEVE-1 1 Guide to Writing Reports discusses sorting 
with multiple sort keys to form control groups. 
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Record Definitions 



4.1 Introduction 

In DATATRIEVE, you define a logical record with the DEFINE RECORD com- 
mand. The logical record is the basic unit that helps you store and interpret data. 
To define the logical record, you combine field definition clauses that specify the 
characteristics of each field. This combination of fields determines the structure 
of the record and represents the relationships among the items of data you store 
in the fields. 

For simple records, you can use the interactive Application Design Tool (ADT). 
Chapter 3 of the Introduction to DA TA TRIEVE-1 1 explains the use of ADT. ADT 
does not allow you to use all the available field definition clauses, however, so you 
cannot use it to define all types of records. 

This chapter briefly explains the elements of a record definition and the record 
and field definition clauses you can use to define records for DATATRIEVE 
domains. For more information about definition clauses, see the alphabetic list- 
ing for each clause in Chapter 5 in this manual. For more information on record 
and field definitions, see Chapter 5 of the DATATRIEVE-1 1 User's Guide. 

4.2 Components of a Record Definition 

A record definition consists of one or more field definitions. Each field definition 
describes the field and its relationship to other fields in the record. 

Every field definition consists of three parts: 

• A level number that determines the relationship between the field and other 
fields in the record 
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• A field name that identifies the field 

• A period (.) that signals the end of the field definition 

Most field definitions also contain one or more field definition clauses. 

Types of Fields 

A record definition can contain both elementary and group fields. An elementary 
field is the basic unit of data. It contains no other field within it. A group field, on 
the other hand, contains elementary or group fields. 

Every record definition must conform to the following rules for including elemen- 
tary and group fields: 

• A record definition must contain at least one elementary field. 

• If a record contains more than one elementary field, it must contain a group 
field that includes all other fields in the record. 

• A group field must contain at least one other field. 
4.3.1 Field Levels 

Level numbers determine the relationship among fields in a record definition. 
The YACHT record definition is shown in Figure 4-1. 

Figure 4-1 The YACHT Record Definition 

01 BOAT 

03 TYPE 

OS MANUFACTURER 
OB MODEL 
03 SPECIFICATIONS 
OB RIG 

OB LENGTH_OMER_ALL 
OB DISPLACEMENT 
OB BEAM 
OB PRICE 

A group field that contains all other fields in a record is at the first or top level. In 
the YACHT record, the group field BOAT contains all other fields in the record 
and is the top level field. 

Second level fields are contained only in a top level field and in no other group 
field. TYPE and SPECIFICATIONS are both second level fields contained in and 
subordinate to the top level field BOAT. TYPE and SPECIFICATIONS are also 
group fields because they contain elementary fields. Fields subordinate only to a 
second level field are third level fields, and so on. MANUFACTURER and 
MODEL in the YACHT record, for example, are third level fields. 
MANUFACTURER and MODEL are also elementary fields since they do not 
contain any lower-level fields. RIG, LENGTH_OVER_ ALL, DISPLACEMENT, 
BEAM, and PRICE are also third level elementary fields. 
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4.3.2 Level Numbers 



Every field in a record definition must have a level number that specifies its rela- 
tionship to the other fields in the record. DATATRIEVE recognizes field levels in 
a record definition according to the level numbers you assign to each field. Thus, 
the level number must be the first element of a field definition. The number of the 
highest possible level is 1, and the number of the lowest possible level is 65. 
Leading zeros, as in 01 and 05, do not affect the value of the level number. 

The top level field must have the smallest level number assigned to any field in 
the record definition. No other field in the record can have the same level number 
as the top level field. The level number usually assigned to the top level field is 
01. Any field with a higher level number is subordinate to the top level field. 

In the YACHT record definition, BOAT is the top level field and is the only field 
with the level number 01. TYPE and SPECIFICATIONS are second level group 
fields and have the same 03 level number. The seven elementary fields are all 
third level fields and have a level number of 06. MANUFACTURER and MODEL 
are subordinate to the TYPE field, while the other five elementary fields are sub- 
ordinate to SPECIFICATIONS. 

The level numbers in the YACHT record definition illustrate several rules about 
assigning level numbers to fields: 

• Only level numbers determine the relationships among fields. 

• Level numbers need not be consecutive. Only the relative value of level num- 
bers determines the relationship between fields. TYPE and 
SPECIFICATIONS, for example, could have level numbers of 02, 04, or 05 and 
the YACHT record structure would still be the same as defined in Figure 4-1. 

• Differences in level numbers mean differences in levels and differences in rela- 
tionship. Fields must have the same level number to be equivalent. If, for 
example, the elementary field LENGTH_OVER_ ALL in the 
SPECIFICATIONS field had a level number of 07, the field immediately pre- 
ceding it, RIG, would become a group field containing LENGTH. OVER_ ALL. 

Fields in the YACHTS record definition and in other examples in this book are 
indented to show their relationship to other fields. Indenting fields helps clarify 
the structure of the record, but has no effect on the relationship among fields. 

Field Names 

In addition to a level number, every field in a record must have a field name. You 
use the field name to identify the field in DATATRIEVE statements and 
DATATRIEVE uses the field name when printing the contents of the field. A field 
name must conform to DATATRIEVE's rules for names: 

• A name can consist of from 1 to 31 letters, digits, hyphens (-), and underscores 
(-). 

• A name must begin with a letter and must end with a letter or digit. 
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• A name cannot duplicate a DATATRIEVE keyword. See Appendix A for a list 
of DATATRIEVE keywords. 

• A name can be continued from one line to another only by using a hyphen (-), 
the DATATRIEVE continuation character. 

• A name can duplicate another field name in the same record definition only if 
the duplicate field names are in different group fields. Duplicating field names 
in a record is not a good data management practice. 

See Chapter 5 of the DATATRIEVE -11 User's Guide for a more detailed list of 
rules for DATATRIEVE names. 

4.4.1 QUERY-NAME and QUERY-HEADER Clauses 

By using the QUERY_NAME clause in a field definition, you can specify an 
alternate name for a field. You can then use the query name in place of the field 
name in DATATRIEVE statements. The YACHT record definition, for example, 
specifies the query name BUILDER for the MANUFACTURER field and the 
query name SPECS for the SPECIFICATIONS field. See Chapter 5 for more 
information on the QUERY_NAME clause. 

You can also specify a QUERY- HEADER for a field. If you do not include a 
QUERY_HEADER clause, DATATRIEVE uses the field name as the column 
header for the field when displaying data. If you include a QUERY_HEADER 
clause in the field definition, DATATRIEVE uses the query header, instead of the 
field name, for the column header. You can override the printing of the field 
name or query header by specifying a column header modifier as part of a print 
list element in the PRINT, SUM, and REPORT statements. See the sections in 
Chapter 5 on these statements for more information. 

4.4.2 FILLER Field Name 

By using the FILLER keyword as the name of an elementary or group field, you 
can mask fields in a data file: 

• Use FILLER as an elementary field to reserve space in the physical record of 
the data file or to suppress the display of fields that you do not want to lose, but 
do not want or need to display. 

• Use FILLER as a group field to access elementary fields in the group and to 
suppress display of the entire group field. 

You cannot retrieve data from or store data in a FILLER field. 

Like other fields, a field named FILLER must have a level number. It can also 
contain field definition clauses. You can use the name FILLER for more than one 
field at the same level in a group field. When you use the PRINT, MODIFY, 
STORE, REPORT, and SUM statements to retrieve, update, or store the contents 
of a record, DATATRIEVE ignores values in FILLER fields. 



4-4 Record Definitions 



Do not use FILLER fields, however, to protect sensitive information stored in 
physical records. The DISPLAY statement displays all the contents of a group 
field, regardless of the field names in the record definition. 

If the FILLER field is an elementary field, you cannot get access to data in the 
field with any statement except DISPLAY. If FILLER is the name of a group 
field, you can access data in the physical record by specifying the name of an ele- 
mentary or group field in the FILLER group field. Each of those fields has its own 
valid name, and you can retrieve the value by specifying that name in a record 
selection expression, a print list, or a field list. You cannot access data in the 
physical record by using the group name (FILLER) or by retrieving for output 
whole records or group fields containing the group field named FILLER. 
DATATRIEVE stops accessing fields in a group when it encounters the name 
FILLER and moves to the next field at the same level or at a higher level. 

The following example shows the use of FILLER fields to mask two elementary 
fields of the PERSONNEL data file, EMPLOYEE .STATUS and SALARY, for 
two different types of retrieval from the same data file: 

DTR> SHOW PERSONNEL© 
DOMAIN PERSONNEL 

USING PERSONNEI REC ON PERSON ♦ DAT 5 

DTR> SHOW PERSONNEL _M(RET) 
DOMAIN PERSONNEL-M 

USING PERSONNEL-MASK ON PERSON 4 DAT 5 
DTR> SHOW PERSONNEL_REC(ret) 

RECORD PERSONNEI REC 

USING 

01 PERSON* 

05 ID PIC IS 9(5), 

05 EMPLOYEE-STATUS PIC IS X(ll) 

QUERY-NAME IS STATUS 

QUERY-HEADER IS "STATUS" 

UALID IF STATUS EQ "TRAINEE" » "EXPERIENCED" 
05 EMPLOYEE-NAME QUERY-NAME IS NAME* 

10 FIRST-NAME PIC IS X(10) 

QUERY-NAME IS F-NAME. 
10 LAST-NAME PIC IS X( 10) 

QUERY-NAME IS L-NAME. 
05 DEPT PIC IS XXX. 

05 START-DATE USAGE IS DATE. 

05 SALARY PIC IS 9(5) 

EDIT-STRING IS *$$,$*$. 
05 SUP- ID PIC IS 9(5) . 

5 

DTR> SHOW PERSONNEL-MASK© 
RECORD PERSONNEL-MASK 
USING 

01 PERSON. 

05 ID PIC IS 9(5) . 

05 FILLER PIC IS X( 1 1 ) 

QUERY-NAME IS STATUS 

QUERY-HEADER IS "STATUS" 

UALID IF STATUS EQ "TRAINEE" » " EX PER I ENCED " 
05 EMPLOYEE-NAME QUERY-NAME IS NAME. 

10 FIRST-NAME PIC IS X(10) 

QUERY-NAME IS F-NAME. 
10 LAST-NAME PIC IS X( 10) 

QUERY-NAME IS L-NAME. 
05 DEPT PIC IS XXX. 

(continued on next page) 
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05 START-DATE USAGE IS DATE, 

05 FILLER PIC IS 3(5) 

EDIT-STRING IS $$$>$$$♦ 
05 SUP_ID PIC IS 3(5) ♦ 

5 

DTR> READY PERSONNEL®) 

DTR > READY PERSONNEL_M© 

DTR> FIND FIRST 5 A IN PERSONNEL© 

C5 records found ] 

DTR > FIND FIRST 5 B IN PERSONNEL_M(RET) 
C5 records found] 
DTR> PRINT A(ret) 







FIRST 


LAST 




START 






SUP 


ID 


STATUS 


NAME 


NAME 


DEPT 


DATE 


SALARY 


ID 


00012 


EXPERIENCED 


CHARLOTTE 


SPIUA 


TOP 


12-Sep 


-72 


$75 


,892 


1 2 


00891 


EXPERIENCED 


FRED 


HOWL 


Fll 


9-Ap r- 


76 


$59 


>594 


1 2 


02343 


EXPERIENCED 


CASS 


TERRY 


D98 


2-Jan- 


80 


$29 


>908 


39485 


12S43 


TRAINEE 


JEFF 


TASHKENT 


C82 


4-Apr- 


81 


$32 


,918 


87465 


32432 


TRAINEE 


THOMAS 


SCHWEIK 


Fll 


7 - N o y - 


81 


$26 


»723 


00891 


DTR > 


PRINT B(E) 




















FIRST 


LAST 


START 


SUP 










ID 


NAME 


NAME 


DEPT DATE 


ID 










1 2 


CHARLOTTE 


SPIMA 


TOP 12-Sep 


-72 


1 2 










00891 


FRED 


HOWL 


Fll 9-Apr- 


76 


1 2 










02943 


CASS 


TERRY 


D98 2-Jan- 


80 


39485 










12G43 


JEFF 


TASHKENT 


C82 4-Apr- 


81 


87465 










32432 


THOMAS 


SCHWEIK 


Fll 7-Nom- 


81 


00891 











DTR> 



4.5 Field Classes 

DATATRIE VE classifies fields in a record by the type of data contained in the 
field and by the way data is stored. Table 4-1 summarizes field classes and their 
content. 



Table 4-1 : Field Classes and Content 



Field Type 


Class 


Content 


Elementary 


Alphanumeric 


Any valid ASCII character 




Numeric 


Any combination of digits and an 
optional sign ( + or -) 




DATE 


A date 




COMPUTED BY 


None; the field definition 
specifies a value expression, but 
no value is stored in the record 


Group 


Alphanumeric 


The values of the fields 
contained in the group field 
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Field Definition Clauses 

When you define a field, you specify its characteristics with one or more optional 
field definition clauses. A field definition clause consists of a keyword, such as 
PICTURE or QUERY_NAME, followed by a character string or value expres- 
sion. 

Use field definition clauses to specify the following field characteristics: 

• The class and length of the data and the format in which the data is stored 
(PICTURE, USAGE, COMPUTED BY, OCCURS) 

• The format for DATATRIE VE to use when writing the data to a file or output 
device (EDIT_ STRING, QUERY_HEADER, SIGN) 

• The values accepted when you store data in the field (VALID IF) 

• The way DATATRIEVE computes numeric values when you refer to the field 
(USAGE, COMPUTED BY) 

• An alternate and equivalent name for the field (QUERY_NAME) 

• An alternate way to DEFINE another field in the record (REDEFINES) 
DATATRIEVE- 11 field definition clauses are summarized in Table 4-2. 
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Table 4-2: Summary of Field Definition Clauses 



Clause 


Type of Field 


Purpose 


COMPUTED BY 


Elementary 


Describes a COMPUTED BY 
field 


EDIT_ STRING 


Elementary 


Specifies the format of a 

value when DATATRIE VE writes 

a field value to a file or 

output device 


OCCURS 


Elementary or group 


Defines multiple occurrences 
of a field or group of 
fields (see Chapter 5 of the 
DA TA TRIEVE-1 1 User's Guide) 


PICTURE 


Elementary 


Specifies the data type, 
length, and format of values 
stored in the field 




Elementary 


Specifies the column header 
for a field when DATATRIE VE 
writes one or more field 
values to a file or output 
device 


QUERY _ NAME 


Elementary or group 


Specifies an alternate name 
for a field 


REDEFINES 


Elementary or group 


Creates an alternate 
definition for a field in 
the record 


SIGN 


Numeric elementary 


Specifies the location and 
representation of the sign 
in a numeric field 


USAGE 


Numeric or date 
elementary 


Specifies the length and 
data type of a numeric field 
or specifies a date field 


VALID IF 


Elementary 


Tests a value against 
conditions specified in a 
Boolean expression before 
storing the value in the 
field 
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When you write field definitions, you should observe these rules and guidelines 
for using field definition clauses: 

• You must include a level number and a field name in the definition of a field. 

• You must include a PICTURE, COMPUTED BY, or USAGE clause in the defi- 
nition of an elementary field. 

• You do not have to include a PICTURE clause for any DATATRIEVE data 
type. When you do specify a PICTURE clause in a field definition, 
DATATRIEVE treats it as an edit string if no EDIT_STRING clause is pre- 
sent. 

• You can use all the field definition clauses listed in Table 4-2 for elementary 
fields. However, you can use only REDEFINES, QUERY_NAME, and 
OCCURS clauses for group fields. DATATRIEVE ignores any PICTURE or 
USAGE clause included in a group field definition. 

• You can put one or more field definition clauses on the same input line as the 
level number and field name. You can also put each field definition clause on 
one or more input lines. Separate each field definition clause from the next by 
entering a space, a tab, or a carriage return. 

• You can enter field definition clauses in any order. 

• You can indent field definition clauses with spaces or tabs or enter them on sep- 
arate lines. This does not change the characteristics of the field, but does make 
record definitions easier to read and understand. 

• You can use only one OCCURS... DEPENDING clause in a record definition. 
No other field definition can follow the last elementary field in a group field 
containing this clause. That is, only subordinate fields can be defined after the 
OCCURS.. .DEPENDING clause. 

• You must end each field definition with a period. If the field is a group field 
with no field definition clause, place the period immediately after the field 
name. If the field definition contains one or more clauses, place the period after 
the last clause. 

You can find detailed descriptions of field definition clauses in the alphabetical 
listings of Chapter 5. 
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Commands, Statements, and Definition Clauses 



Introduction 

This chapter describes all DATATRIEVE-11 commands, statements, record defi- 
nition clauses, and field definition clauses. Table 5-1 lists the commands, state- 
ments, and clauses in alphabetical order. Table 5-2 lists frequently performed 
functions and the commands, statements, and clauses you can use to perform 
them. 

The remainder of the chapter describes each command, statement, and clause, in 
alphabetical order. Each section of the chapter has the same format and consists 
of the following categories of information: 

• Function 

The function statement briefly describes the function or effect of the command, 
statement, or clause. 

• Format 

The format indicates the spelling and placement of keywords and the place- 
ment of required and optional syntax elements for the entry. As a rule, you 
cannot abbreviate command and statement names and other keywords. The 
sequence of syntax elements is also critical. You must follow the sequence 
shown in the format. If you omit an optional element, leave its relative position 
in the command, statement, or clause empty and proceed to the remaining ele- 
ments in a left-to-right order. If necessary, review the documentation conven- 
tions listed at the end of this section. 
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• Arguments 

Arguments describe the components of the command, statement, or clause. 

• Restrictions 

Restrictions tell you what requirements and limits there are on the use and 
action of the command, statement, or clause. They also list the access privi- 
leges you must have to use the entry. 

• Results 

Results tell you what action DATATRIE VE takes when you use the command, 
statement, or clause. 

• Usage Notes 

Usage Notes describe common uses of the command, statement, or clause and 
indicate what other language elements you can use in conjunction with the 
command, statement, or clause. 

• Examples 

Examples show the use of representative sequences of commands, statements, 
and clauses. In the case of clauses, they show sample record or field definitions. 

The following symbols and conventions are used in syntax formats: 



Convention 


Meaning 


UPPERCASE WORDS 
lowercase words 

{} 
[] 


Uppercase words in the text are DATATRIEVE keywords. 

Lowercase words are generic terms that indicate entries you must 
provide. 

Braces mean you must choose one, but no more than one, of the 
enclosed entries. 

Brackets mean you have the option of choosing one, but no more than 
one, of the enclosed entries. 

A horizontal ellipsis means you have the option of repeating the preced- 
ing element of the syntax format. 

A vertical ellipsis means you have the option of repeating an element of 
the syntax format on the succeeding line. 
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Table 5-1 : Alphabetical Summary of Commands, Statements, and Clauses 



Language Element 


Function 


(CO = Command) 
(CL = Clause) 
(S = Statement) 
(KVV - rteport writer; 




: (Invoke Procedure) (CO) 


invokes a jj a i a i kijii v Hi procedure 


©(Invoke Command File) (CO) 


Invokes a command file 


ABORT (S) 


Ends statement, procedure, or command file execution 


ADT (CO) 


Invokes Application Design Tool (ADT) 


ALLOCATION (CL) 


Specifies type of word boundary alignment for storing and 
retrieving records 


Assignment (S) 


Assigns a value to an elementary field, group field, or variables 


AT BOTTOM (RW) 


Prints summary lines at the bottom of a report, a page, or a 
control group 


Al lUr (r(W) 


Prints header lines or summary lines at the top of a report, a 
page, or a control group 


BEGIN-END (S) 


Groups statements into one compound statement 


CLOSE (CO) 


Closes the file created by the OPEN command 


COMPUTED BY (CL) 


Describes a COMPUTED BY field 


DECLARE (S) 


Defines a variable 


DECLARE PORT (S) 


Creates a temporary port 


DEFINE DICTIONARY (CO) 


Creates a private data dictionary 


DEFINE DOMAIN (CO) 


Creates a domain definition 


DEFINE FILE (CO) 


Creates a data file for a domain 


DEFINE PORT (CO) 


Creates a port definition 


DEFINE PROCEDURE (CO) 


Creates a procedure definition 


DEFINE RECORD (CO) 


Creates a record definition 


DEFINE TABLE (CO) 


Creates a dictionary table definition 


DEFINEP(CO) 


Adds an entry to an access control list (ACL) 


DELETE (CO) 


Removes a definition from a data dictionary 


DELETEP (CO) 


Removes an entry from an access control list (ACL) 


DISPLAY (CO) 


Displays on your terminal the unformatted value of a single 
value expression 



(continued on next page) 
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Table 5-1 : Alphabetical Summary of Commands, Statements, and Clauses (Cont.) 



Language Element 


Function 


DROP(S) 


Removes a record from a collection but not from its data file 


EDIT (CO) 


Invokes the DA I A 1 K1E VE Editor 


EDlI_blKlNG(CL) 


specifies the format ot a field value when it is printed 


END .REPORT (RW) 


Ends a report specification 


ERASE (S) 


Removes a record from an indexed or relative data file 


EXIT (CTRL/Z) (CO) 


Ends a DATATRIE VE session 


EXTRACT (CO) 


Copies the definition of a dictionary element into a command 
file 


FIND (S) 


Retrieves a record and establishes a current collection 


FINISH (CO) 


Ends control over and frees space occupied by a domain and its 
associated collections 


FOR (S) 


Causes execution of one or a series of statements for a specified 
record 


HELP (CO) 


Provides online assistance for a command, a statement, or a 
clause 


TT7! mTTT7i"\T T7"T QT7 1 fC\ 

Ir - 1 riEN -ELsE (b ) 


Executes either of two statements, depending on the evaluation 
of a Boolean expression 


MODIFY (S) 


Changes field contents of a specified record 


ULbUKo (CL) 


Defines multiple occurrences of a field or a group of fields 


OPEN (CO) 


Creates a tile that records user/DAl A1K1E VE dialogue 


PIC rURE (CL) 


O • n i-i n j „ nil i ■ i • , ] • l 

Specifies the format ot a field value as it is stored in a record 


PRINT (S) 


Displays a value expression according to a specified format 


PRINT (RW) 


Specifies format of the reported data 


QUERY _ HEADER (CL) 


Specifies the column header for the field value when it is 
printed 


QUERY _NAME (CL) 


specifies an alternate name lor a field 


READY (CO) 


Gives access to a domain 


REDEFINES (CL) 


Creates an alternate definition for a field 


RELEASE (CO) 


Ends control over and frees space occupied by a specified collec- 
tion, table, or global variable 


REPEAT (S) 


Executes a statement a specified number of times 


REPORT (S) 


Invokes the Report Writer 


SELECT (S) 


Selects a record in a collection 



(continued on next page) 
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Table 5-1 : Alphabetical Summary of Commands, Statements, and Clauses (Cont.) 



Language Element 


Function 


SET (CO) 


Establishes the current data, dictionary, sets the maximum 
number of columns per page, controls the use of forms, the dis- 
play of prompts and the effect of ABORT, and starts Guide 
Mode 


SET (RW) 


Specifies the report header, name, date, length, and width of a 
report 


SHOW (CO) 


Displays information about the data dictionary and its contents 


SHOWP(CO) 


Displays the access control list (ACL) associated with a diction- 
ary object 


SIGN (CD 


Specifies the location and representation of the sign in a 
numeric field 


SORT(S) 


Sorts records in a collection 


STORE (S) 


Creates and stores a record in a domain 


SUM (S) 


Provides a summary of totals for a specified numeric field 


THEN (S) 


Joins two or more statements into a compound statement 


USAGE (CL) 


Specifies the internal storage format of a field or specifies a date 
field 


VALID IF (CD 


Tests a value before storing it in a field 


WHILE (S) 


Causes repetition of a statement while a specified condition is 
true 
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Table 5-2: Summary of Commands, Statements, and Clauses by Function 



Function 


Language Element 


Combining/repeating statements 




Creating a compound statement 


THEN 
BEGIN-END 


Repeating a statement 


REPEAT 


Executing a statement 
conditionally 


IF-THEN-ELSE 
WHILE 


Applying a statement to a 
record 


FOR 


Data dictionaries 




Creating a data dictionary 


DEFINE DICTIONARY 


Establishing a current 
dictionary 


SET DICTIONARY 


Displaying the file 
specification of the current 
dictionary 


SHOW DICTIONARY 


Deleting the definition of a 
dictionary element 


DELETE 


Dictionary tables 




Creating a dictionary table 


DEFINE TABLE 


Modifying a dictionary table 


EDIT 


Copying a dictionary table to 
a command file 


EXTRACT 


Releasing a dictionary table 


RELEASE 


Displaying dictionary table 
names and definitions 


SHOW 



(continued on next page) 
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Table 5-2: Summary of Commands, Statements, and Clauses by Function (Cont.) 



Function 


Language Element 


Domains 




Readying a domain for use 


READY 


Creating a domain definition 


DEFINE DOMAIN 
ADT 


Creating a data file for a 

UUIIldill 


DEFINE FILE 


Deleting a domain definition 


DthLtEj 1 ill 


Copying a domain definition 
to a command file 


EXTRACT 


Releasing control of a domain 


FINISH 


Displaying a domain name or 
definition 


SHOW 


Ending execution 


ABORT 


Handling records 




Printing a record/field value 


PRINT 
REPORT 

QTTM 


^\.UUlIlg d X CCUI U LU ct UUIIldill 


1 vyXVUi 


Forming a collection of 
records 


TTT'NT'n 
r liNJJ 


Selecting a record 




Sorting a record 


SORT 


Removing a record from a 
collection 


DROP 


Deleting a record from a file 


ERASE 


Changing a field value 


MODIFY 


Recording a DATATRIE VE session 


OPEN 
CLOSE 



(continued on next page) 
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Table 5-2: Summary of Commands, Statements, and Clauses by Function (Cont.) 



Function 


Language Element 


Online assistance 




Defining a domain, record, 
and data file 


ADT 


Enabling/disabling statement 
prompting 


SET PROMPT 


Printing command/statement 

lnffYirn^'H nn 


HELP 


otdx ting vjru.iu.fc; iviuut; 


SET GUIDE 


Access control lists (ACL) 




Deleting an entry 


DELETEP 


Adding an entry 


DEFINEP 


Printing contents on a 
terminal 


SHOWP 


Ports 




Creating a temporary port 


DECLARE PORT 


Defining a port 


DEFINE PORT 


Mr l Otcll III cs 




Creating a procedure 


DEFINE PROCEDURE 


Deleting a procedure 


DELETE 


Modifying a procedure 


EDIT 


Copying a procedure to a 
command file 


EXTRACT 


Displaying procedure names 
and definitions 


SHOW 



(continued on next page) 
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Table 5-2: Summary of Commands, Statements, and Clauses by Function (Cont.) 



Function 


Language Element 


Record Definitions 




Creating a record definition 


DEFINE RECORD 
ADT 


Copying a record definition 
to a command file 


EXTRACT 


Displaying a record name and 
definition 


SHOW 


Specifying a record word 
boundary in storage 


ALLOCATION 


Describing a COMPUTED BY 
field 


COMPUTED BY 


Specifying a print edit 
string 


EDIT_ STRING 


Defining a multiple field 
occurrence 


OCCURS 


Specifying the format of a 
field value 


PICTURE 


Specifying a column header in 
a print statement 


QUERY _ HEADER 


Specifying an alternate field 
name in a print statement 


QUrLiKY _N AMU/ 


definition for a field 


ixiiiUiitr iiN no 


Specifying a sign in a 
numeric field 


SIGN 


Specifying the internal 
storage format of a numeric 
or date field 


USAGE 


Specifying a VALID IF test 
during storage 


VALID IF 


Terminating DATATRIE VE 


EXIT (CTRL/Z) 


Variables 




Defining a variable 


DECLARE 


Assigning a value to a 
variable 


Assignment 


Releasing a variable 


RELEASE 
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: (Invoke Procedure) 



5.2 : (Invoke Procedure) 

Function 

Invokes a DATATRIEVE procedure. 
Format 



{ : } procedure-name 



Arguments 

procedure-name 

Is the name of the DATATRIEVE procedure you want to invoke. 
Restrictions 

• You must have DATATRIEVE E (EXECUTE/EXTEND) access to a procedure 
before you can invoke it. 

• You cannot invoke a procedure during an ADT, Edit or Guide Mode session. 

• You cannot invoke a procedure in the definition of a domain, record, or table. 

• You should not allow a procedure to invoke itself, either directly or indirectly; 
you may create an infinite loop. 

• A procedure invoked from a BEGIN-END block cannot include a FIND, 
SELECT, or DROP statement. 

Results 

• If the procedure consists of full commands or statements, DATATRIEVE 
executes each command or statement in the procedure in order. 

• If the procedure contains only a clause or an argument for a command or state- 
ment, DATATRIEVE includes the procedure within the command or state- 
ment invoking the procedure. 

Usage Notes 

• You can nest procedures by invoking a procedure within another procedure, 
but you must be careful not to allow the procedure to invoke itself. 

• You can invoke a procedure a specified number of times by including it in a 
REPEAT statement. You can also apply a procedure to a collection of records 
by invoking the procedure in a FOR statement. You must, however, use care 
when invoking a procedure in these statements. For example, the following 
syntax can be used, but the results may be unexpected: 

REPEAT n :procedure-name 
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: (Invoke Procedure) 
Continued 



This statement does not execute the procedure n times. When DATATRIEVE 
encounters the first complete statement in the procedure, it assumes that the 
REPEAT statement is also complete. Therefore, it executes the first statement 
in the procedure n times. DATATRIEVE then executes the remaining com- 
mands or statements in the procedure once. 

• To repeat the entire procedure n times, enclose the procedure invocation in a 
BEGIN-END block: 

REPEAT n 
BEGIN 

procedure-name 

END 

Use a similar technique for controlling procedures invoked in a FOR loop. For 
example: 

FOR rse 
BEGIN 

:procedure-name 

END 
Examples 

Define and then invoke a procedure to find the employee in PERSONNEL with 
the largest salary: 



DTR > DEFINE PROCEDURE MAX-SALARY© 

DFN > READY PERSONNEL® 

DFN > PRINT PERSONNEL WITH SALARY 

DFN > END-PROCEDURE© 

DTR > SHOW MAX_SALARY© 

PROCEDURE MAX_SALARY 

READY PERSONNEL 

PRINT PERSONNEL WITH SALARY 
END-PROCEDURE 
DTR > : MAX_SALARY© 



FIRST LAST 
ID STATUS NAME NAME 

00012 EXPERIENCED CHARLOTTE SPIMA 

D T R > 



= MAX SALARY OF PERSONNEL© 

= MAX SALARY OF PERSONNEL 

START SUP 
DEPT DATE SALARY ID 

TOP 12-Sep-1372 $75 »892 00012 
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: (Invoke Procedure) 
Continued 



Define a procedure that displays employee records in a given department with 
salaries greater than $40,000, then invoke this procedure three times: 

DTR> SET NO PROMPT© 

DTR > DEFINE PROCEDURE BIG-SALARY© 

DFN> FOR PERSONNEL WITH DEPT = * • " t h e department"© 

DFN> BEGIN© 

D F N > IF SALARY GT 40000© 

DFN > THEN PRINT PERSON© 

DFN> END© 

DFN> END_ PROCEDURE© 

DTR> REPEAT 3© 

C0N> BEGIN© 

C0N> :BIG_SALARY© 

C0N> END© 

Enter the department: F 1 1 © 





FIRST 


LAST 






START 






SUP 


ID 


STATUS NAME 


NAME 


DEPT 




DATE 


SALARY 


ID 


0089 1 


EXPERIENCED FRED 


HOWL 


Fl 1 


9 


-Apr-197B 


$59 


♦ 594 


1 2 


78923 


EXPERIENCED LYDIA 


HARRISON 


Fl 1 


19 


- Jun- 1979 


$40 


,747 


00891 


Enter 


the department: T32© 
















38482 


EXPERIENCED BILL 


SWAY 


T32 


5 


-Ma>'- 1980 


$54 


1 


1 2 


83764 


EXPERIENCED JIM 


MEADER 


T32 


4 


-Ap r- 1980 


$41 


»029 


87289 


Enter 


the department: TOP© 
















00012 


EXPERIENCED CHARLOTTE 


SPIOA 


TOP 


12 


-Sep-1972 


$75 


,892 


1 2 



DTR > 



Invoke a procedure that specifies an edit string clause for a variable: 

DTR > SET NO PROMPT© 
DTR > SHOW E_S© 
PROCEDURE E_S 

EDIT-STRING IS $$»$$$, 99 
END-PROCEDURE 

DTR > DECLARE PRICE_PER_FT COMPUTED BY PRICE/LOA :E_S.© 
DTR > PRINT TYPE t PRICE-PER-FT OF FIRST 5 YACHTS© 



PRICE 
PER 

MANUFACTURER MODEL FT 



ALBERG 
ALB I N 
ALBIN 
ALBIN 
AMERICAN 



37 MK 
79 

BALLAD 

VEGA 

28 



I I 



$998*67 
$688 , 4S 
$918 ♦ BS 
$888 ♦ 88 
$380,57 



DTR > 
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@ (Invoke Command File) 



@ (Invoke Command File) Command 

Function 

Invokes a command file. 
Format 



@ file-spec 



Arguments 

file-spec 

Is the file specification of the file you want to execute. 
Restrictions 

• The @ command must be on a line by itself. 

• You must have operating system read access to a command file before you can 
invoke it. 

• You cannot invoke a command file from a procedure, but you can include a 
command file in a procedure. When you enter @ file-spec in response to the 
DFN> prompt, DATATRIEVE includes the statements of the command file in 
the procedure as though you had just typed them yourself. The resulting proce- 
dure succeeds or fails depending on the logic of the statements in the command 
file. 

• You cannot invoke command files while you are in ADT or Guide Mode. 

• You cannot invoke a command file in a loop created by the FOR, REPEAT, or 
WHILE statements. 

• You cannot invoke a command file within a BEGIN-END block. 

• You should not allow a command file to invoke itself, either directly or indi- 
rectly; you can create an infinite loop. 

• You should not put incomplete commands or statements in the middle of a com- 
mand file. DATATRIEVE looks at the next entry in the command file for the 
completion of the command or statement and displays an error message if the 
command or statement is not completed. 
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@ (Invoke Command File) 
Continued 



Results 



• If you do not specify a file type for the command file, DATATRIEVE uses a 
.CMD file type as a default. 

• If the command file consists of full commands or statements, DATATRIEVE 
executes each command or statement in the command file in order. 

• If the command file ends with an incomplete DATATRIEVE command or state- 
ment, DATATRIEVE returns a CON> prompt, waiting for you to supply the 
missing elements. 

Usage Note 

To include comments in a command file, place an exclamation mark (!) before 
each comment line. 



Invoke a command file, BUILDR.CMD, to produce a report on YACHTS by a spe- 
cified builder: 

DTR> @BU I LDR(RET) 
READY YACHTS 

REPORT YACHTS WITH BUILDER = *, BUILDER 
SET COLUMNS-PAGE = 70 
PRINT BOAT 
END-REPORT 

Enter BUILDER: ALB IN© 



Example 



1 l-0ct-1383 
PaSe 1 



MANUFACTURER 



MODEL 



RIG 



LENGTH 
OVER 
ALL 



WEIGHT 



BEAM 



PRICE 



ALBIN 
ALBIN 
ALBIN 



79 

BALLAD 
MEGA 



SLOOP 
SLOOP 
SLOOP 



26 
30 
27 



il ,200 
7 »27G 
5 »070 



10 
10 
08 



$17 *900 
$27 »500 
$18 *S00 



DTR > 
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ABORT Statement 

Function 

Stops the execution of either a single statement or an entire procedure or com- 
mand file. 

Format 



ABORT [value-expression] 



Arguments 

value-expression 

Is a DATATRIEVE value expression, usually a character string literal. 
Restriction 

The ABORT statement affects the outermost statement that contains it. When a 
statement contains nested FOR loops, you cannot use an ABORT statement to 
transfer control from an inner loop to an outer loop. Similarly, when a statement 
contains nested BEGIN-END blocks, you cannot use an ABORT statement to 
transfer control from an inner block to an outer one. 

Results 

• The ABORT statement does not end an interactive DATATRIEVE session. 
During an interactive session, DATATRIEVE stops executing the statement 
that contains the ABORT statement, displays a message containing the value 
of the value expression specified in the ABORT statement, and returns control 
to DATATRIEVE command level (indicated by the DTR> prompt): 

DTR > SET NO PROMPT® 

DTR > DECLARE X PIC XXX .(gg) 

DTR > X = " DEF "(RED 

DTR> IF X = "ABC " THEN PRINT X ELSE © 
CON> ABORT "X does not enual ABC "(ret) 

ABORT: X does not equal ABC 
Execution terminated by "ABORT" statement 
DTR > 

• During an interactive session, if the ABORT statement is in a procedure or 
command file, the result depends on whether SET ABORT is in effect: 

- If SET ABORT is in effect, DATATRIEVE returns to command level without 
executing the rest of the procedure or command file when the ABORT state- 
ment is encountered. 

- If SET NO ABORT is in effect, DATATRIEVE stops execution of the state- 
ment that contains the ABORT statement and then executes any statements 
and commands remaining in the procedure or command file. 
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• If you invoke DATATRIE VE from operating system level with an invocation 
command line, the effect of an ABORT statement depends on whether SET 
ABORT is in effect: 

- If SET ABORT is in effect, DATATRIE VE returns to the operating system 
command level without executing the rest of the command file. 

- If SET NO ABORT is in effect, DATATRIE VE stops executing the statement 
containing the ABORT statement and then processes any statements and 
commands remaining in command file. 

• If the ABORT statement occurs in a STORE or MODIFY statement, 
DATATRIEVE does not store a new record or modify the target record. 

• When you submit a batch stream containing a DATATRIEVE command file, 
any ABORT statements in the command file behave as they would if you had 
entered them during an interactive session: 

- Whether SET ABORT is in effect or not, DATATRIEVE prints a message 
containing the value of the value expression specified in the ABORT state- 
ment in the log file of the batch job. 

- If SET ABORT is in effect and DATATRIEVE processes an ABORT state- 
ment in a procedure or command file, DATATRIEVE returns to 
DATATRIEVE command level without executing the rest of the procedure 
or command file. 

- If SET NO ABORT is in effect and DATATRIEVE processes an ABORT 
statement in a procedure or command file, DATATRIEVE stops executing 
the statement containing the ABORT statement and then processes any 
statements and commands remaining in the procedure or command file. 

- If you invoke DATATRIEVE with an invocation command line in the batch 
stream and DATATRIEVE processes an ABORT statement, SET ABORT 
ends the DATATRIEVE session and returns control of the process to the 
batch stream. SET NO ABORT aborts the current statement, and 
DATATRIEVE processes the remaining statements in the command file. 

If the batch stream contains other command files queued after the 
DATATRIEVE command file, the processing of a DATATRIEVE ABORT state- 
ment does not end the batch job. 

Usage Note 

Use an IF-THEN-ELSE statement to establish conditions for the ABORT state- 
ment (see Section 5.35.) The Boolean expression in the IF clause establishes the 
conditions that control the ABORT statement. The ABORT statement executes 
when: 

• The Boolean expression is true and the ABORT statement is in the THEN 
clause. 

• The Boolean expression is false and the ABORT statement is in the ELSE 
clause. 
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Examples 

Store a record in the YACHTS domain, using an ABORT statement to stop the 
operation if the value of the BEAM field is zero: 

DTR> SET NO PROMPT© 

DTR> STORE YACHTS VERIFY USING© 

DTR > IF BEAM EQ THEN ABORT "Bad value for BEAM "(ret) 

Enter MANUFACTURER: AMERICAN© 

Enter MODEL: 1980© 

Enter RIG: SLOOP© 

Enter LENGTH_OVER_ALL : 25© 

Enter DISPLACEMENT: 7500© 

Enter BEAM: 0© 

Enter PRICE: 10000© 

ABORT: Bad value for BEAM 

Execution terminated by "ABORT" statement 
DTR > 

Define a procedure to write a report on the current collection. Use the ABORT 
statement to stop the entire procedure if there is no current collection to report 
on: 

DTR> SET NO PROMPT© 

DTR > DEFINE PROCEDURE YACHT-REPORT© 
DFN > SET ABORT© 

D F N > PRINT "Have you established a current collection?"© 

DFN > IF *."YES or NO" CONTAINING " N " THEN© 

DFN> ABORT "Sorry--no collection* no report."® 

DFN> REPORT© 

DTR > PRINT BOAT© 

DFN > AT BOTTOM OF REPORT PRINT COUNT* TOTAL PRICE© 
DFN > END-REPORT© 
DFN > END-PROCEDURE© 
DTR > :YACHT_REPORT© 

Have you established a current collection? 
Enter YES or NO: NO© 

ABORT: Sorry --no collection* no report* 
Execution terminated by "ABORT" statement 
DTR > 
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Define a procedure to update the OWNERS domain after the sale of a boat. Check 
the boat in question against the inventory in the YACHTS domain and abort the 
procedure if the boat is not in YACHTS. Then, check the OWNERS domain for a 
record of the boat. If a record exists, change the owner's name and update the 
boat name if desired. If no record exists, store a new record in the OWNERS 
domain. The procedure requires MODIFY or WRITE access to the OWNERS 
domain for the update and EXTEND or WRITE access for the entry of a new 
record. The example aborts because there is no YACHTS record for an ALBERG 
42. The value expression specified in the ABORT statement includes the 
variables BLD and MOD: 

DTR > SHOW SALE-BOAT® 
PROCEDURE SALE-BOAT 
READY YACHTS WRITE 
READY OWNERS WRITE 
SET ABORT 

DECLARE BLD PIC X< 10) . 
DECLARE MOD PIC X( 10) ♦ 
BLD = *♦ "BUILDER 'S NAME " 
MOD = *♦ "MODEL" 

IF NOT ANY YACHTS WITH (BUILDER = BLD AND MODEL = MOD) THEN 
BEGIN 

PRINT "Record not found in yachts*" 

ABORT "Possible inventory error f o r- - " ! ! BLD ! MOD 

END ELSE 

PRINT "Yachts record found for " ! BLD ! MOD 
IF ANY OWNERS WITH (BUILDER = BLD AND MODEL = MOD) THEN 
BEGIN 

FOR OWNERS WITH (BUILDER = BLD AND MODEL = MOD) 
MODIFY USING 

BEGIN 

PRINT COL 10 » NAME 

NAME = *»"New owner's name" 

PRINT COL 10 f BOAT-NAME 

IF *. "Change boat name? Y/N" 

CONTAINING "Y" THEN PRINT SKIP THEN 
BOAT-NAME = *»"New boat name" 

END 

END ELSE 

STORE OWNERS USING 
BEGIN 

NAME = #« "New owner's name" 
BOAT-NAME = *."Boat name" 
BUILDER = BLD 
MODEL = MOD 

END 

END-PROCEDURE 

DTR > : SALE-BOAT© 

Enter Builder's name: ALBERG© 

Enter Model: 42©) 

Record not found in yachts. 

ABORT: Possible inventory error f o r- -ALBERG 42 
Execution terminated by "ABORT" statement 
DTR > 



5-1 8 Commands, Statements, and Definition Clauses 



ADT 



ADT Command 

Function 

Invokes the Application Design Tool (ADT), an interactive aid that helps you 
define a domain, its associated record, and its data file. 

Format 



ADT 



Arguments 

None. 
Restrictions 

• You cannot invoke ADT from an application program using the 
D AT ATRIE VE- 1 1 Call Interface. 

• Do not use the ADT command in a command file. 

• The record definition and data file definition created by ADT do not contain all 
the features, clauses, and options available when using the DATATRIEVE 
DEFINE commands. 

• See the following commands for the access privileges needed to add the domain 
and record definitions to the dictionary and to define the data file for the 
domain: DEFINE DOMAIN, DEFINE RECORD, DEFINE FILE, and 
DELETE. 

Results 

• DATATRIEVE invokes the Application Design Tool, which asks you a series of 
questions about the domain, the size and type of the fields you want in the 
record, and the name and type of the data file. 

• ADT writes a command file you can invoke at DATATRIEVE command level. 

• If you respond to any of ADT's questions with a CTRL/Z, DATATRIEVE dis- 
plays the message "ADT exited by user request" and returns control to 
DATATRIEVE command level. 

Example 

Invoke the Application Design Tool. 

DTR> ADT© 

Do you want help? (YES or NO) : 

See Chapter 3 of Introduction to DATATRIEVE-11 for a sample ADT session and 
more information on ADT. 
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5.6 ALLOCATION Clause 

Function 

Specifies the type of word boundary alignment DATATRIEVE uses when storing 
records in a data file associated with the record definition. It also controls the way 
DATATRIEVE retrieves data from files created by user programs or other 
applications. 



Format 



ALLOCATION IS 



MAJOR-MINOR 

ALIGNED_MAJOR_MINOR 

LEFT-RIGHT 



Arguments 

MAJOR-MINOR 

Causes DATATRIEVE to force word boundary alignments according to data 
types for elementary fields defined with the USAGE IS COMP SYNC clause 
and to force group fields to the maximum alignment of the elementary fields 
contained within the group field. MAJOR-MINOR is the default for VAX-11 
DATATRIEVE and VAX-11 COBOL. 



ALIGNED_MAJOR_MINOR 



Causes DATATRIEVE to force word boundary alignments according to data 
types for all elementary fields in the record and group fields to the maximum 
alignment of the elementary fields they contain. 
ALIGNED_MAJOR_MINOR is the default for COBOL-81. 



LEFT-RIGHT 

Causes DATATRIEVE to force word boundary alignment for elementary 
fields defined as COMP, COMP_l, COMP-2, and DATE. LEFT-RIGHT is 
the default alignment for DATATRIEVE-11, COBOL-11, and COBOL-74. 



Restriction 

When defining a record for an existing data file, the alignment type of the record 
definition must match the alignment type of the data file. 
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Results 

• For records with ALIGNED_MAJ OR_MINOR allocation and for fields with 
USAGE IS COMP SYNC clauses in records with MAJOR-MINOR allocation, 
DATATRIE VE aligns fields on word boundaries. When DATATRIE VE shifts a 
field to the next word boundary, the bytes skipped (filler bytes) are considered 
part of the record. 

• The number of filler bytes DATATRIE VE inserts when 
ALIGNED_MAJOR_MINOR or MAJOR-MINOR is in effect depends on the 
data type and/or the length of the field: 

- Fields declared COMP (INTEGER) always begin on one-word boundaries. 

- Fields declared COMP_l (REAL) always begin on two-word boundaries, 
while fields declared COMP (INTEGER) that are from five to nine digits 
long also begin on two-word boundries. 

- Fields declared DATE or COMP_2 (DOUBLE) always begin on four-word 
boundaries. Fields declared COMP (INTEGER) that are from 10 to 18 digits 
long are also aligned on four-word boundries. 

• When the allocation is either MAJOR-MINOR or 
ALIGNED_MAJOR_MINOR, the group field boundaries are aligned accord- 
ing to the maximum alignment of the elementary fields that comprise the 
group. 

• When the allocation is LEFT_RIGHT, fields begin on word boundaries if they 
are declared DATE, COMP_2 (DOUBLE), or COMP_l (REAL). 

Usage Notes 

• The ALLOCATION clause is an optional record definition clause. When you 
include it in a record definition, it affects the way DATATRIEVE handles the 
internal storage and retrieval of data in some or all of the fields in your data 
file. 

• If you want to use DATATRIEVE- 11 on data files created with VAX-11 
DATATRIEVE, you must add an ALLOCATION MAJOR-MINOR clause to 
the DATATRIEVE- 1 1 record definition. This ensures that DATATRIEVE- 11 
can interpret the VAX-11 data correctly. 
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Example 

Define records without an ALLOCATION clause (the default is LEFT_RIGHT) 
and with MAJOR-MINOR alignment. Specify USAGE IS COMP SYNC for one 
MAJOR-MINOR record and USAGE IS COMP for another MAJOR-MINOR 
reeord. 

dtr> i© 

DTR> ! Define a record with default allocation© 

DTR > \<m 

DTR > DEFINE RECORD A_REC USING© 

DFN> 01 TOP.© 

DFN> 03 CHAR PIC X.© 

DFIM > 03 NUM USAGE IS COMP ♦© 

DFN > ;© 

[Record A_REC is 4 bytes lonsH 
DTR > !© 

DTR > ! Define a record with MAJOR-MINOR allocation© 
DTR> ! and no SYNC clause© 
DTR> !© 

DTR > DEFINE RECORD B_REC USING© 

DFN > ALLOCATION IS MAJOR-MINOR® 

DFN> 01 TOP,® 

DFN> 03 CHAR PIC X.© 

DFN> 03 NUM USAGE IS COMP.© 

DFN > 5© 

[Record B_REC is 3 bytes lonsfJ 
DTR > !© 

DTR> ! Define a record with MAJOR-MINOR allocation© 
DTR > ! and a USAGE IS COMP SYNC clause© 
DTR > !© 

DTR> DEFINE RECORD C-REC USING© 
DFN > ALLOCATION IS MAJOR-MINOR© 
DFN > 01 TOP.© 

dfn> 03 char pic x.© 

dfn > 03 num usage is comp sync© 

dfn > ;© 

[Record C_REC is 4 bytes Ions] 
DTR > 
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Assignment Statement 

The assignment statement assigns a value to an elementary field, a group field, 
or a variable. 

5.7.1 Assigning a Value to an Elementary Field 
Function 

Assigns a value to an elementary field in a MODIFY or STORE statement. 
Format 

field-name = value-expression 

Arguments 

field-name 

Is the name of an elementary field. 

value-expression 

Is the value to be assigned to the field. This argument can be any 
DATATRIEVE value expression. (See Chapter 2.) 

Restrictions 

• The equal sign ( = ) is not the same as the relational operators EQ or EQUAL; 
it is the assignment operator that tells DATATRIEVE to store the value on the 
right in the field specified on the left. 

• This type of assignment statement can be used only in the USING clause in a 
MODIFY or STORE statement (see Sections 5.35 and 5.53). 

• To use the assignment statement in a USING clause in a STORE statement, 
you must ready the domain for WRITE or EXTEND access. To use this state- 
ment in a USING clause in a MODIFY statement, you must ready the domain 
for WRITE or MODIFY access (see the READY command, Section 5.42.) 

• You cannot assign a value to a COMPUTED BY field. 
Results 

• DATATRIEVE stores the value of the value expression in the specified field, 
performing any datatype conversions necessary. 
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• If the value expression is a prompting value expression^ . prompt-name), 
DATATRIEVE prompts for the value of the field. DATATRIEVE reprompts for 
the value if any of the following occurs: 

- Truncation error: you have entered more characters than the field definition 
allows. 

- Conversion error: you have entered a character that is inappropriate for the 
field, such as a letter in a numeric field. 

- Sign error: you have entered a minus sign in an unsigned numeric field. 

- VALID IF error: you have entered an invalid value in the field. That is, the 
Boolean expression specified in the VALID IF clause in the record definition 
is evaluated as false because the value specified in the assignment state- 
ment is not a valid value for the field. See Chapter 4 for more information on 
record definitions and field definition clauses. 

• If the value expression is not a prompting value expression and truncation, 
conversion, or sign errors occur, DATATRIEVE accepts the value with a 
warning: 

- If you enter too many digits for a numeric field, DATATRIEVE truncates the 
high-order digits and stores the remaining digits in the field. 

- If you enter too many characters for an alphanumeric field, DATATRIEVE 
truncates the rightmost characters and stores the remaining characters in 
the field. 

- If a VALID IF failure occurs, DATATRIEVE does not execute the assign- 
ment statement and does not execute the STORE or MODIFY statement 
containing the assignment statement. 

Usage Notes 

• If you want DATATRIEVE to check your values for validity and give you the 
opportunity to recover from an error caused by invalid input, use a prompting 
value expression in the USING clause of a MODIFY or STORE statement: 

field-name = *. prompt-string 

This type of assignment statement provides the only way to recover from trun- 
cation, conversion, sign errors, or VALID IF failures and is especially useful 
when you are creating records with the STORE statement. 

• If you are unsure of the name of a field or the type of data it contains, use the 
SHOW FIELDS command (see Section 5.49). SHOW FIELDS displays a brief 
description of each field in a readied domain. 
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Examples 

Ready the YACHTS domain for WRITE access, then store a record in the domain 
for the manufacturer CHALLENGER: 

DTR> READY YACHTS WRITE© 

DTR> STORE YACHTS USING MANUFACTURER = "CHALLENGER" (ret) 
DTR> PRINT YACHTS WITH BUILDER EQ "CHALLENGER "(ret) 

LENGTH 
OYER 

MANUFACTURER MODEL RIG ALL WEIGHT BEAM PRICE 

CHALLENGER 00 

CHALLENGER 32 SLOOP 32 12,800 11 $31,835 

CHALLENGER 35 SLOOP 35 14,800 12 $39,215 

CHALLENGER 41 KETCH 41 28,700 13 $51,228 

DTR> 

Ready the YACHTS domain for MODIFY access, then change the value of the 
PRICE field in the first record to a new value: 

DTR> READY YACHTS MODIFY© 
DTR> FIND YACHTS© 
C 1 13 records found ] 
DTR> SELECT© 

DTR> PRINT PRICE THEN MODIFY USING PRICE = *."NEW PRICE"© 

PRICE 
$38 ,951 

Enter NEW PRICE: 39000© 
DTR> PRINT PRICE© 

PRICE 

$39 ,000 

DTR> 

5.7.2 Assigning a Value to a Group Field 
Function 

Assigns a value to a group field in a MODIFY or STORE statement. 
Format 



group-field-name-1 = group-field-name-2 
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Arguments 

group-field-name- 1 

Is the name of a group field to which you want to assign a value. 
group-field-name-2 

Is the name of a group field containing the values you want to assign to group 
field 1. 

Restrictions 

• The equal sign ( = ) is not the same as the relational operators EQ or EQUAL. 
It is the assignment operator that tells DATATRIE VE to store the value on the 
left in the field specified on the right. 

• This type of assignment statement can be used only in a USING clause in a 
MODIFY or STORE statement (see Section 5.35 and 5.53). 

- To use the assignment statement in the USING clause of a MODIFY state- 
ment, you must ready the domain containing group field 1 for MODIFY or 
WRITE access. 

- To use the assignment statement in the USING clause of a STORE state- 
ment, you must ready the domain for WRITE or EXTEND access (see the 
READY command, Section 5.42). 

• Both group field 1 and group field 2 must have at least one elementary field 
with the same field name or query name. 

Result 

DATATRIEVE changes the values of all fields in group field 1 to the values of 
identically named fields in group field 2. All unmatched elementary fields in 
group field 1 are set to zero (numeric fields) or blank (string fields) in a STORE 
statement that does not contain explicit assignments. Unmatched fields remain 
unchanged in a MODIFY statement. Use explicit assignments in the STORE 
statement to assign values to unmatched fields in group field 1 . 

Examples 

Store a record in the YACHTS domain with the same values in the group field 
SPECIFICATIONS (query name SPECS) as the selected record: 

DTR> SET NO PROMPT® 

DTR > READY YACHTS WRITE® 

DTR> FIND YACHTS© 

C113 records found] 

DTR > SELECT®) 

DTR > PRINT SPECS® 

(continued on next page) 
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LENGTH 
' OVER 

RIG ALL WEIGHT BEAM PRICE 

KETCH 37 20*000 12 $3G»951 

DTR> STORE YACHTS USING© 
CON> BEGIN© 

CON> BUILDER = **BUILDER© 

CON> SPECS = SPECS© 

CON> END© 

Enter BUILDER: HUGHES© 

DTR > PRINT YACHTS WITH BUILDER = "HUGHES "© 

LENGTH 
OVER 

MANUFACTURER MODEL RIG ALL WEIGHT BEAM PRICE 

HUGHES KETCH 37 20 »000 12 *36»951 

DTR > 



Store records in a new domain called PRICED_YACHTS. Store only boats that 
have a price: 

DTR > SET NO PROMPT© 

DTR > DEFINE DOMAIN PR I CED_Y ACHTS USING YACHT ON PYACHT.DAT?© 
DTR > DEFINE FILE FOR PR I CED_Y ACHTS© 
DTR > READY PRICED-YACHTS WRITE© 
DTR > FOR YACHTS WITH PRICE NE 0® 

CON> STORE PRICED-YACHTS USING BOAT=BOAT© 

DTR> FIND PRICED-YACHTS© 
[50 records found] 
DTR> 



5.7.3 Assigning a Value to a Variable 



Function 

Assigns a value to a variable. 
Format 



variable-name = value-expression 



Arguments 

variable-name 

Is the name of a variable that has been defined with a DECLARE statement, 
value-expression 

Is the value to be assigned to the specified variable. 
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Restrictions 

• The equal sign ( = ) is not the same as the relational operators EQ or EQUAL. 
It is the assignment operator that tells DATATRIEVE to store the value on the 
left in the field specified on the right. 

• You can use this type of assignment statement anywhere a DATATRIEVE 
statement is allowed. 

• You must define the variable name with the DECLARE statement (see Section 
5.11) before you can assign a value to it. 

Results 

• DATATRIEVE assigns the specified value to the variable. 

• If the value expression is a prompting value expression^ . prompt-name), 
DATATRIEVE prompts for the value of the field. DATATRIEVE reprompts for 
the value if any of the following occurs: 

- Truncation error: you have entered more characters than the field definition 
allows. 

- Conversion error: you have entered a character that is inappropriate for the 
field, such as a letter for a numeric field. 

- Sign error: you have entered a minus sign for an unsigned numeric field. 

- VALID IF error: you have entered an invalid value for the field. That is, the 
Boolean expression specified in the VALID IF clause in the record definition 
is evaluated as false if the value specified in the assignment statement is not 
a valid value for the field. See Chapter 4 for more information on record defi- 
nitions and field definition clauses. 

• If the value expression is not a prompting value expression and truncation, 
conversion, or sign errors occur, DATATRIEVE accepts the value with a 
warning: 

- If you enter too many digits for a numeric field, DATATRIEVE truncates the 
high-order digits, stores the remaining digits in the field. 

- If you enter too many characters for an alphanumeric field, DATATRIEVE 
truncates the rightmost characters and stores the remaining characters in 
the field. 

- If a VALID IF failure occurs, DATATRIEVE does not execute the assign- 
ment statement. 
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Usage Notes 

• If you want DATATRIE VE to check your values for validity and give you the 
opportunity to recover from an error caused by invalid input, use a prompting 
value expression: 

field-name = *. prompt-string 

This type of assignment statement provides the only way to recover from trun- 
cation, conversion, sign errors, or VALID IF failures and is especially useful 
when you are creating records with the STORE... USING statement. 

• Use the assignment statement to assign the current system date to a date field. 
Define a date field with the USAGE IS DATE clause and then assign the cur- 
rent system date to the field with the DATATRIEVE date value expression, 
"TODAY": 

DTR> DECLARE CURRENT-DATE USAGE DATE .(RET) 
DTR> CURRENT_DATE = "TODAY"© 
DTR> PRINT CURRENT_DATE(ret) 

CURRENT 
DATE 

lG-Feb-83 

DTR> 



Examples 

Declare the global variable NEW_PRICE. Assign a value to it: 

DTR > DECLARE NEW-PRICE PIC 3(5) EDIT.STRING IB $$$,$$$♦© 
DTR> NEW-PRICE = " $25 > 000 "© 
D T R > PRINT NEW-PRICE© 

NEW 
PRICE 

$25 tOOO 
DTR > 
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Declare two global variables. Assign the value in the PRICE field of the first boat 
in YACHTS, and then assign the value of OLD_PRICE to NEW-PRICE: 

DTR > DECLARE NEW-PRICE PIC 9(5).© 
DTR > DECLARE OLD-PRICE PIC 9(5).© 
DTR> FIND YACHTS? SELECT 5 PRINT PRICE© 

PRICE 

$36 >95i 

DTR > OLD-PRICE = PRICE© 
DTR > PRINT OLD-PRICE© 

OLD 
PRICE 

$36 #951 

DTR > NEW-PRICE = OLD-PRICE© 
DTR > PRINT NEW-PRICE© 

NEW 
PRICE 

$36 >951 

DTR > 
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BEGIN-END Statement 

Function 

Groups DATATRIEVE statements into a single compound statement called a 
BEGIN-END block. 

Format 



BEGIN 

statement- 1 
[statement-2] 



END 



Arguments 

statement 

Is a DATATRIEVE statement. Within the BEGIN-END block, terminate 
each statement with a semicolon, a RETURN, or both. 

Restrictions 

• Do not use FIND, SELECT, or DROP statements in a BEGIN-END block. 

• Observe all restrictions on statements included in the BEGIN-END block. This 
manual lists these restrictions in the descriptions of the various statements. 

• Do not use DATATRIEVE commands in a BEGIN-END block. You cannot 
include a procedure that contains DATATRIEVE commands, nor can you 
invoke a command file that contains DATATRIEVE commands in a BEGIN- 
END block. 

• Do not store a command file invocation in a BEGIN-END block. When you type 
@file-name within a BEGIN-END block, DATATRIEVE immediately 
executes the command file, and all the statements in the file become part of the 
BEGIN-END block just as though you had typed them yourself. 

Results 

• DATATRIEVE executes statements in a BEGIN-END block in sequential 
order. 

• When the BEGIN-END block includes a DECLARE statement, the variable it 
defines is a local variable. You cannot refer to a local variable from outside the 
BEGIN-END block. DATATRIEVE automatically releases all local variables 
when it finishes executing the BEGIN-END block in which they are defined. 
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• If a BEGIN-END block that defines a local variable is in a FOR loop or 
REPEAT statement, DATATRIEVE initializes the local variable each time it 
executes the BEGIN-END block. The variable is initialized to zero if numeric 
or blank if string. See Section 5.11 for information about the DECLARE state- 
ment. 

• When you create a single BEGIN-END block interactively, DATATRIEVE 
prompts you, after you press RETURN, for the elements needed to complete an 
individual statement or to complete the block. The CON> prompt indicates 
that DATATRIEVE is ready for you to continue entering statements or ele- 
ments of statements into the BEGIN-END block. After you enter END, 
DATATRIEVE executes all the statements in the BEGIN-END block. When 
DATATRIEVE completes the last statement in the BEGIN-END block, you see 
the DTR> prompt indicating you have returned to DATATRIEVE command 
level. 

• When you are entering nested BEGIN-END blocks interactively, 
DATATRIEVE does not execute any of the statements in the nested blocks 
until you enter the END that completes the outermost BEGIN-END block. 
DATATRIEVE continues to prompt with CON> until you enter the END that 
completes the outermost BEGIN-END block. 

• If you enter CTRL/C while DATATRIEVE is executing the statements in a 
BEGIN-END block, DATATRIEVE does not execute any of the remaining 
statements that follow in the block. DATATRIEVE treats the whole BEGIN- 
END block as one statement, regardless of the number of statements or nested 
BEGIN-END blocks it contains. Because CTRL/C cancels the execution of the 
current statement, it cancels the execution of the remaining outermost 
BEGIN-END block, regardless of the number of levels of other BEGIN-END 
blocks nested in it. 

• If a statement in a BEGIN-END block prompts for a value and you enter a 
CTRL/C, DATATRIEVE reprompts for the value. To end the execution of a 
BEGIN-END block, enter CTRL/Z in response to the prompt. DATATRIEVE 
then stops executing the outermost BEGIN-END block and returns you to 
DATATRIEVE command level. 

Usage Notes 

• You can use a BEGIN-END block anywhere you can use a DATATRIEVE 
statement. 

• You can nest BEGIN-END blocks. The only limit to the number of levels of 
nested BEGIN-END blocks you can form is the amount of system pool avail- 
able at any given time. If you exceed this limit, DATATRIEVE stops executing 
statements and signals an error. Your only option at this point is to reduce the 
levels of BEGIN-END block nesting. 

• To repeat an entire sequence of DATATRIEVE statements, put the statements 
in a BEGIN-END block, and put the BEGIN-END block in a REPEAT state- 
ment. 
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• To repeat all statements in a procedure, invoke the procedure in a BEGIN- 
END block, and put the BEGIN-END block in a REPEAT statement. If you 
invoke a procedure in a REPEAT statement (REPEAT n :procedure-name), 
DATATRIE VE repeats the first statement of the procedure n times and then 
executes the other statements in the procedure one time each. 

• Use a BEGIN-END block to include more than one DATATRIE VE statement 
in a FOR loop. 

• Use a BEGIN-END block to include more than one DATATRIE VE statement 
in the THEN and ELSE clauses in an IF-THEN-ELSE statement. 

• When storing or modifying records, use BEGIN-END blocks to include more 
than one statement in the USING and VERIFY USING clauses of the STORE 
and MODIFY statements. 

• When you invoke a procedure that uses consecutive PRINT statements to for- 
mat output, the line spacing changes when you invoke the procedure in a 
BEGIN-END block. The one blank line between the result of each PRINT 
statement disappears. To preserve that spacing when you include the proce- 
dure in a BEGIN-END block, edit the procedure and insert a SKIP print list 
element at the beginning of the second and each succeeding PRINT statement. 

Examples 

Store five records in the domain PHONES, each having LOCATION MB1-H2 
and DEPARTMENT CE. The SET NO PROMPT command suppresses the 
"[Looking for...]" prompts that precede each CON> prompt. This example also 
shows how DATATRIE VE responds to CTRL/Z when prompting for input: 

DTR> SHOW PHONES© 
DOMAIN PHONES 

USING PHONE-REC ON PHONE 4 DAT 5 
DTR > SHOW PHONE-REC© 
RECORD PHONE-REC 

USING 
01 PH0NE_REC* 

03 NAME PIC >(( 10) ♦ 

03 NUMBER PIC X < 8 ) ♦ 

03 LOCATION PIC X( 10) ♦ 

03 DEPARTMENT PIC X(3> ♦ 

5 

DTR> READY PHONES WRITE© 
DTR> SET NO PROMPT© 

DTR> REPEAT 5 STORE PHONES USING© 
C0N> BEGIN© 

C0N> NAME = * . NAME© 

C0N> NUMBER = *. NUMBER© 

C0N> LOCATION = "MB1-H2"© 

C0N> DEPARTMENT = "CE"© 

C0N> END© 

Enter NAME: FRED© 

Enter NUMBER: 555-1243© 

Enter NAME: KAREN© 

Enter NUMBER: 423-9981© 

Enter NAME: A Z 

Execution terminated by operator 
DTR > 
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Use a BEGIN-END block to put three statements in the USING clause of a 
MODIFY statement. Print a YACHTS record, modify the price, and print the 
result of the modification and the next record to modify: 

DTR> READY YACHTS WRITE© 

DTR> SET NO PROMPT© 

DTR> FOR YACHTS WITH PRICE = 0© 

C0N> MODIFY USING© 



C0N> BEGIN© 

C0N> PRINT© 

C0N> PRICE = **"NEW PRICE"© 

C0N> PRINT© 
C0N> END© 



LENGTH 
OVER 

MANUFACTURER MODEL RIG ALL WEIGHT BEAM PRICE 

BLOCK I* 40 SLOOP 39 18*500 12 

Enter NEW PRICE: 30000 

LENGTH 
OVER 

MANUFACTURER MODEL RIG ALL WEIGHT BEAM PRICE 

BLOCK I. 40 SLOOP 39 18*500 12 $30*000 

BUCCANEER 270 SLOOP 27 5*000 08 

Enter NEW PRICE: A Z 

Execution terminated by operator 

DTR > 

Use a BEGIN-END block in a REPEAT statement to repeat an entire procedure: 

DTR > SET NO PROMPT© 

DTR > DEFINE PROCEDURE LOOP- EXAMPLE© 

DFN > PRINT "Show how a BEGIN-END worKs with REPEAT "© 

DFN> PRINT "and more than one statement"© 

DFN > END -PROCEDURE© 

DTR> REPEAT 2© 

C0N> : LOOP-EXAMPLE© 

Show how a BEGIN-END works with REPEAT 

Show how a BEGIN-END works with REPEAT 

and more than one statement 

DTR > REPEAT 2© 
CON> BEGIN© 

CON> :LOOP_EXAMPLE© 
CON> END® 

Show how a BEGIN-END works with REPEAT 
and more than one statement 
Show how a BEGIN-END works with REPEAT 
and more than one statement 

DTR > 
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CLOSE Command 



Function 

Closes an RMS log file created with an OPEN command. A log file records your 
interactive dialogue with DATATRIEVE. 

Format 



CLOSE 



Arguments 

None. 
Restriction 

You can use the CLOSE command only at DATATRIEVE command level in 
response to the DTR> prompt. 

Results 

• DATATRIEVE closes the log file created by the OPEN command. The CLOSE 
command has no effect on the location of the log file, which is catalogued in the 
directory determined by the file specification entered in the OPEN command 
(see Section 5.37). 

• DATATRIEVE also closes a log file when you exit from DATATRIEVE. 
Usage Note 

The CLOSE command allows you to close a log file without ending an interactive 
DATATRIEVE session. 

Example 

Open a log file, display a record, then close the file: 

DTR > OPEN LOG© 

DTR > SHOW FAMILY-REC© 

RECORD FAM I LY-REC 

01 FAMILY* 

03 PARENTS. 

OS FATHER PIC X( 10) . 
OS MOTHER PIC X( 10) ♦ 
03 NUMBER_K IDS PIC 99 ED I T_STR I NG IS Z9. 

03 KIDS OCCURS TO 10 TIMES DEPENDING ON NUMBER-K IDS . 
OS EACH-KID. 

09 K I D_NAME PIC X < 1 ) QUERY-NAME IS KID. 
09 AGE PIC 99 ED I T_STR I NG IS Z9 . 

5 

DTR > CLOSE® 
DTR > 
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5.1 COMPUTED BY Clause 

Function 

Describes a COMPUTED BY field. 
Format 



COMPUTED BY value-expression 



Arguments 

value-expression 

Is a value expression consisting of one or more field or query names, numeric 
literals, and arithmetic operators. This includes concatenation expressions, 
table expressions, and statistical expressions. 

Restrictions 

• This clause is valid for elementary fields only. 

• You cannot use an OCCURS clause or a VALID IF clause in a COMPUTED BY 
field. 

• You cannot use a COMPUTED BY field as a sort key in SORT and SUM state- 
ments or in the SORTED BY clause of record selection expressions. 

• Because it does not exist in the record, you cannot assign a value to a 
COMPUTED BY field. STORE and MODIFY statements cannot refer to a 
COMPUTED BY field. 

• You cannot redefine a COMPUTED BY field with the REDEFINES clause. 

• Because a COMPUTED BY field is a virtual expression, you cannot use a 
clause such as PICTURE or USAGE that specifies how the value is stored. 

Result 

When you refer to the COMPUTED BY field in a statement, DATATRIE VE 
resolves the field name to the nearest single record context and evaluates the 
value expression after the field using the field value(s) in that record. See 
Chapter 12 in the DATATRIEVE-11 User's Guide for more information on 
COMPUTED BY fields. 

Usage Notes 

• COMPUTED BY fields are useful if you display arithmetic computations fre- 
quently. A COMPUTED BY field allows you to specify the computation once in 
the record definition, then print its value simply by referring to its field name. 
Generally, the computation includes the name of one or more fields in the 
record definition. 
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• A COMPUTED BY field does not occupy space in a record. It exists solely in the 
record definition as a virtual field. DATATRIEVE calculates the value of a 
COMPUTED BY field only when you use the field in a statement. 

• If you include a COMPUTED BY clause in a field definition, you do not have to 
include any other field definition clause. However, you may want to specify the 
format of the computation with an EDIT_ STRING clause. 

Examples 

Compute the price per pound of a yacht as the price divided by the displacement. 
In this case, both the PRICE and DISP fields are defined in the record definition: 

OS PRICE_PER_POUND 

EDIT-STRING $$*»$*9.93 
COMPUTED BY PRICE/DISP. 

When you use the PRICE_PER_POUND field in a command or statement, 
DATATRIEVE divides the value of the record's PRICE field by the value of its 
DISP field. The result of the computation is then the value of the 
PRICE_PER_POUND field. 

Derive the value of the SALESMAN field from a dictionary table named 
SALESMEN: 

OG SALESMAN 

EDIT-STRING IS ><<20) 

COMPUTED BY MANUFACTURER VIA SALESMEN* 

In this example, DATATRIEVE uses the value of the MANUFACTURER field in 
the current record to search the dictionary table SALESMEN for a matching 
code. If one is found, DATATRIEVE uses its translation as the value of the 
SALESMAN field. 
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5.1 1 DECLARE Statement 

Function 

Defines a global or a local variable. 
Format 



DECLARE variable-name variable-definition. 



Arguments 

variable-name 

Is the name of the variable being defined. The name must conform to the rules 
for names listed in Chapter 4. 

variable-definition 

Is the definition of the variable, which consists of field definition clauses. If 
you include more than one such clause, separate them with spaces or tabs. 

. (period) 

Ends the DECLARE statement. 

Restrictions 

• You must include at least one COMPUTED BY, PICTURE (PIC), or USAGE 
clause in the variable definition to specify the data type, length, scale, and edit 
string of the variable. 

• Although you can include other field definition clauses, you cannot use an 
OCCURS clause or REDEFINES clause in the variable definition. A variable 
can have only the properties of an elementary, nonrepeating field in a 
DATATRIEVE record definition. 

• You must explicitly initialize all global variables. DATATRIEVE does not ini- 
tialize global variables. 

Results 

• When you use a DECLARE statement at DATATRIEVE command level, 
DATATRIEVE creates a global variable. A global variable exists until you 
redeclare it, end the DATATRIEVE session, or explicitly release the variable 
with the RELEASE command. 
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• Unless you define a global variable with a COMPUTED BY clause, the global 
variable retains the value you assign it until you assign a new value to it, rede- 
clare it, end the DATATRIE VE session, or explicitly release the variable with 
a RELEASE command. The value of a global variable defined with a 
COMPUTED BY clause depends on the value expression that controls the com- 
putation. If the value expression is based on the value of a field in a record, the 
variable has a value only when there is a valid single record context in which 
to resolve the value expression. 

• When you use a DECLARE statement in another DATATRIEVE statement, 
such as a BEGIN-END or THEN statement, DATATRIEVE creates a local 
variable. A local variable exists only within the statement in which it is defi- 
ned. DATATRIEVE releases all local variables created within a statement 
when it encounters the end of that statement. 

For example, if you define a local variable in the third BEGIN-END block in a 
series of four nested BEGIN-END blocks, you can refer to, assign values to, and 
retrieve values from the variable in the third and fourth blocks. That is, after 
DATATRIEVE executes the DECLARE statement in the third block, the value 
of the variable can be changed or retrieved by any of the remaining statements 
in the third block, including any of the statements in the fourth and innermost 
block. That local variable, however, has no meaning for any statement outside 
those two inner blocks. No statement in the first or second block and outside 
the two inner blocks can refer to the local variable defined in the third one. 

• If the statement that defines a local variable is in a FOR loop or REPEAT 
statement, the local variable is initialized each time DATATRIEVE executes 
the statement. The initial value DATATRIEVE assigns to the variable 
depends on the field definition clauses included in the DECLARE statement 
that defined the variable. Numeric variables are initialized to zero, and alpha- 
numeric and alphabetic variables are initialized as blanks. 

Usage Note 

To assign a value to a variable, use the following type of assignment statement: 
variable-name = value-expression 

See Chapter 2 and Section 5.7.3 in this manual for more information on assign- 
ing a value to a variable. 

Examples 

Declare the global variable NEW_BEAM as a two-digit numeric field with an 
edit string of Z9: 

DTR> DECLARE NEW_BEAM PIC 99 ED I T_STR I IMG IS Z9»© 
DTR> NEW_BEAM = 9© 
DTR> PRINT NEW-BEAM© 

NEW 
BEAM 

9 

DTR > 
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Declare the global variable X as an integer number: 

DTR> DECLARE X USAGE IS COMP,© 
DTR> )< = 36© 
DTR> PRINT X© 

X 

36 

DTR> SHOW F I ELDS© 
Global variables: 
X [Number] 

DTR> RELEASE X© 
DTR> SHOW FIELDS© 

No Domains Readied or Global Variables Declared 
DTR> 

Declare the variable DUE as a date. Assign today's date to DUE and suppress the 
header with a hyphen in parentheses: 

DTR> DECLARE DUE USAGE IS DATE*© 
DTR> DUE = "TODAY"© 
DTR> PRINT DUE (-)© 
22-Sep-83 

DTR > 

Use the SHOW FIELDS command to display the names and types of currently 
defined global variables: 

DTR > DECLARE X USAGE COMP.© 
DTR > DECLARE Y PIC 9(5),© 
DTR > DECLARE A PIC XX,© 
DTR > DECLARE B PIC AAA,© 
DTR> SHOW FIELDS© 
Global variables : 

B [Character string] 

A [Character string] 

Y [Number] 

X [Number] 

DTR > 



Use the RELEASE command (see Section 5.44) to remove global variables from 
your workspace and from the context stack: 



string] 
string] 



DTR> RELEASE X » A© 
DTR> SHOW FIELDS© 
Global variables: 

B [Character string] 

Y [ N u m b e r ] 

DTR > 



DTR> SHOW FIELDS© 
Global variables: 

B [Character 
A [Character 
Y [Number] 
X [Number] 
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5.1 2 DECLARE PORT Statement 

Function 

Creates a temporary DATATRIE VE port with the name you specify and readies 
the port for WRITE access. DATATRIE VE does not enter a definition of the port 
in the data dictionary. 

Format 

DECLARE PORT port-name USING 
level-number-1 field-definition-1 . 
[level-number-2 field-definition-2.] 

[level-number-n field definition-n.] 



Arguments 

port-name 

Is the name of the port. It cannot duplicate a DATATRIEVE keyword or the 
given name of any domain you may bring into your workspace. 

level-number 

Is the level number for the field in the port declaration that indicates the rela- 
tionship of the field to the other fields of the port. 

field-definition 

Is a field definition. A field definition must end with a period. A port declara- 
tion must have at least one field definition. 

; (semicolon) 

Ends the port declaration. 

Restrictions 

• You cannot invoke a procedure in a port declaration. 

• You must include at least one PICTURE (PIC) clause or one USAGE clause in 
the port declaration. 
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Results 

• The semicolon (;) is required to end a port declaration. DATATRIEVE contin- 
ues to prompt with CON> until you type a semicolon and press RETURN or 
until it detects a syntax error. If you make a syntax error when declaring a 
port, DATATRIEVE returns to command level without creating the port. 

• If your application program declares a port at DATATRIEVE command level, 
DATATRIEVE creates a global port that is available to your application pro- 
gram until you end your access to it with the FINISH command or until you 
end the DATATRIEVE session. A global port is similar to a global variable. 

• If your application program declares the port in a compound statement, 
DATATRIEVE creates a local port that is available only for the remainder of 
the statement in which it is declared, and for those statements contained in the 
statement in which it is declared. A local port is similar to a local variable. 

Usage Notes 

• You cannot ready a declared port. 

• See the DATATRIEVE-11 Call Interface Manual for examples and informa- 
tion about using a port to transfer data between DATATRIEVE and your 
application program. 
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5.13 DEFINE DICTIONARY Command 



Function 

Creates a file for D ATATRIE VE to use as a data dictionary and connects you to 
the newly created dictionary. 



Format 



DEFINE DICTIONARY file-spec 



Arguments 

file-spec 

Is the file specification for the data dictionary in the following format: 

For RSTS/E systems: dev:[PPN]file-name.type 

For RSX systems: dev:[UIC]file-name.type;ver 

You must name at least one field in the file specification. DATATRIEVE uses 
the following defaults for fields not specified: 

Field Default 

dev: SY: (the system device) 

[UIC/PPN] Your default UIC/PPN 

file-name QUERY 

.type .DIG 

;ver 1 or next higher version 

(non-RSTS/E systems only) 

Restriction 

You must have W (WRITE) access to the specified dictionary. 
Results 

• DATATRIEVE creates an empty indexed file for use as a data dictionary. 

• If you do not enter a file specification on the same input line as DEFINE 
DICTIONARY, DATATRIEVE prompts with DFN>. After you specify a file, 
you return to the DATATRIEVE command level, indicated by the DTR> 
prompt. 

• DATATRIEVE makes the newly created dictionary your current dictionary. 
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Usage Notes 

• To verify the creation of the new dictionary, use the SHOW DICTIONARY 
command. DATATRIEVE displays the name of the new dictionary as the cur- 
rent dictionary. To return to your login default dictionary, use the SET 
DICTIONARY command. 

• Use the following commands to define objects in your dictionary: 

- DEFINE DOMAIN 

- DEFINE PORT 

- DEFINE PROCEDURE 

- DEFINE RECORD 

- DEFINE TABLE 

For information on defining a database instance, see the 
DA TA TRIEVE-1 1/DBMS-l 1 Interface Manual. 

Examples 

Define a file named NEWDIC on the system device for use as a data dictionary. 
The file will have the same UIC/PPN as your default UIC/PPN and a type of 
.DIC. The current dictionary is OLDDIC.DIC: 

DTR > SHOW DICTIONARY© 

The current dictionary is SY : [ 5G > 22 ] OLDD I C , D I C 5 1 
DTR> DEFINE DICTIONARY NEWDIC© 
DTR > SHOW DICTIONARY© 

The current dictionary is SY : C 5B t 22 1 NEWD I C ♦ D I C 5 1 
DTR > 

Define a data dictionary on a given device in a given directory, assign the diction- 
ary the name MYDATA.DIC, confirm its creation, and reset the current 
dictionary: 

DTR > DEFINE D I CT I ONARY© 
DFN > DB2: C33 1 1 7 ] MYDATA ♦ D I C© 
DTR > SHOW DICTIONARY© 

The current dictionary is DB2 : [ 33 » 1 7 ] MYDATA , D I C 5 1 
DTR > SET DICTIONARY NEWDIC© 
DTR > SHOW DICTIONARY© 

The current dictionary is SY : C 33 » 1 7 ] NEWD I C , D I C 5 1 
DTR > 
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5.1 4 DEFINE DOMAIN Command 



The DEFINE DOMAIN command stores a domain definition in your current dic- 
tionary. You can define domains for single RMS files or domains for a view of one 
or more domains. 



5.14.1 Defining an RMS Domain 



Function 

Stores a domain definition in your current dictionary and creates an access con- 
trol list (ACL) for the domain. 



Format 



DEFINE DOMAIN domain-name USING record-name 



(passwd) 
. (*) . 



ON file-spec 



Arguments 

domain-name 

Is the name of the domain being defined. It must conform to rules for 
DATATRIEVE-1 1 dictionary object names. 

record-name 

Is the name of the record definition to be associated with the domain. Before 
you can ready the domain, use the DEFINE RECORD command (See Section 
5.18) to enter this record definition in the same dictionary. 

(password) 
(*) 

Is the password D ATATRIEVE will use to check that you have E (EXECUTE/ 
EXTEND) privilege for the record definition. Use a password only if the 
record definition already exists. Use (*) to have DATATRIEVE prompt you 
for the password. 

file-spec 

Is the file specification of the RMS file containing the data for the domain. 
This file does not have to exist until you try to ready the domain. The file spe- 
cification has the following format: 

For RSTS/E systems: dev:[PPN]file-name.type 

For RSX systems: dev:[UIC]file-name.type;ver 
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You must specify at least one field. On RSTS/E systems, you must specify a 
file name. All other fields are optional. If you omit fields in the file specifica- 
tion, DATATRIEVE uses the following defaults: 



Field 


Default 


dev: 


SY: (the system device) 


[UIC/PPN] 


Your default UIC/PPN 


file-name 


No default 


•type 


.DAT 


;ver 


1 or next higher version number 




(non-RSTS/E systems only) 



; (semicolon) 

Ends the domain definition. 
Restrictions 

• You cannot invoke a procedure in a domain definition. 

• Do not assign a domain a name that duplicates a DATATRIEVE keyword. 
Results 

• DATATRIEVE prompts you with the DFN> prompt until you type a semico- 
lon and press RETURN or until it detects a syntax error. If you make a syntax 
error, DATATRIEVE returns to command level (indicated by the DTR> 
prompt) without creating a domain definition. 

• DATATRIEVE enters the domain definition in your current dictionary and 
creates an access control list (ACL) for the domain by entering a UIC/PPN in 
the ACL with full access privileges (RWMEC). The actual UIC/PPN stored in 
the list depends on your installation. Refer to Chapter 20 in the 

DA TA TRIEVE-1 1 User's Guide for more information. 

Usage Notes 

• The record and the data file associated with the domain need not be defined 
when you issue a DEFINE DOMAIN command. 

• You cannot modify a domain definition with the DEFINE DOMAIN command. 
Make the desired changes. When you exit from the Editor, DATATRIEVE 
installs the updated domain definition in your current dictionary. See Chapter 
17 of the DA TA TRIEVE-1 1 User's Guide and Section 5.25 of this manual for 
information on using the DATATRIEVE Editor. 
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Examples: 

Define the domain PHONES. Use the record definition PHONE_REC. Specify 
PHONE.DAT as the input data file: 

DTR > DEFINE DOMAIN PHONES USING® 
DFN > PHONE_REC ON PHONE.DAT© 
DFN > ;(U 
DTR> 

Define the domain HOUSE. Use HOUSE_REC as the associated record and store 
the data in the file DB2:[202,202]HOUSE.DAT. 

DTR > DEFINE DOMAIN HOUSE USING© 

DFN > HOUSE.REC ON DB2 : C 202 ,202 ] HOUSE . DAT® 

DFN > ;® 

DTR > 

5.1 4.2 Defining a View Domain 
Function 

Stores a view domain definition in your current dictionary and creates an ACL 
entry for the domain. 

Format 



DEFINE DOMAIN view-name OF domain-name [,...] USING 

level-number-1 field-name-1 OCCURS FOR rse-1 . 

. . ^ o * ■ w of OCCURS FOR rse-2 } 
level-number-2 field-name-2 { . n > 

( FROM domain-name-2 ) 



Arguments 

view-name 

Is the name of the view being defined. The name cannot duplicate the name of 
any other object in the same dictionary. 

domain-name 

Is the name of a domain containing the records to be included in the view. 
You cannot use the name of the view. When specifying more than one 
domain, use a comma to separate each domain name from the next. 
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level -number 

Is the level number for a field in the view definition, 
field-name 

Is the name of a field in the view definition. 

A field-name followed by an OCCURS FOR rse clause has no relationship to 
any field in the domain or domains specified in the RSE. 

A field-name followed by a FROM domain-name clause must be the name of a 
field in a domain specified in the OF domain-name clause. 

OCCURS FOR rse 

Establishes the field as a list, and indicates that the associated field is to be 
included in the view only for those records specified by the RSE. The RSE 
must contain a reference to one of the domains listed in the OF domain-name 
clause. 

FROM domain-name 

Indicates that the definition of the associated field is identical to that of the 
field of the same name in the domain specified by domain-name. The argu- 
ment domain-name must be the same as that used in the preceding OCCURS 
FOR rse clause. 

. (period) 

Ends a field definition. 
; (semicolon) 

Ends the domain definition. 
Restrictions 

• The view definition must contain an OCCURS FOR rse clause as the top-level 
field and at least one FROM domain-name clause. 

• The restrictions on defining RMS domains apply to defining view domains. 
Results 

• DATATRIEVE prompts you with the DFN> prompt until you type a semico- 
lon and press RETURN or until it detects a syntax error. If you make a syntax 
error, DATATRIEVE returns to command level (indicated by the DTR> 
prompt) without creating a view domain definition. 

• DATATRIEVE enters the view domain definition in your current dictionary 
and creates an access control list (ACL) for the domain by entering a UIC/PPN 
in the ACL with full access privileges (RWMEC). 
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Usage Notes 

To include an entire record in a view field, specify the top-level field as the field 
name. To include only selected fields from a record, name each field you want in 
the view on a separate line. 

See Chapter 14 of the DATATRIEVE-11 User's Guide for information on using 
views. 

Example 

Define a view of big yachts, ready the view domain, and print the first five records 
in the domain: 

DTR> DEFINE DOMAIN BIGGEST- YACHTS OF YACHTS USING© 

DFN> 01 BIGGEST_ YACHT OCCURS FOR YACHTS WITH LOA GT 40.© 

DFN > 03 BUILDER FROM YACHTS,© 

DFN> 03 MODEL FROM YACHTS* © 

DFN > 03 PRICE FROM YACHTS,© 

DFN > ;© 

DTR> READY YACHTS© 

DTR> SET NO PROMPT© 

DTR> READY BIGGEST - YACHT S© 

DTR> PRINT FIRST 5 BIGGEST-YACHTS© 

MANUFACTURER MODEL PRICE 

CHALLENGER 41 $51 ,228 

COLUMBIA 41 $48,490 

GULFSTAR 41 $41 ,350 

ISLANDER FREEPORT $54,970 

NAUTOR SWAN 41 

DTR> 



See Chapter 14 of the DATATRIEVE-11 User's Guide for more examples of view 
definitions. 
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5.1 5 DEFINE FILE Command 

Function 

Creates an RMS sequential or indexed sequential data file for the DATATRIEVE 
RMS domain specified in the command. 

Format 

For Sequential Files: 



DEFINE FILE [FOR] domain-name [,] 




" ALLOCATION = n " 






SUPERSEDE 


[.-] 




MAX 





For Indexed Sequential Files: 



DEFINE FILE [FOR] domain-name [,] 




"ALLOCATION = n" 






SUPERSEDE 


[.-..] 




MAX 






{KEY = field-name-1 


[ ( [NO] CHANGE [,] [NO] DUP ) ] ( [,...] 



Arguments 

domain-name 

Is the name of the DATATRIEVE RMS domain for which you want to create a 
data file. 

ALLOCATION = n 

Specifies an unsigned, nonzero integer that determines the number of disk 
blocks initially allocated for the data file. If you omit this argument, zero 
blocks are allocated for the file. 

SUPERSEDE 

Deletes any data file with a complete file specification exactly duplicating 
that specified in the RMS domain definition and replaces it with the new file 
DATATRIEVE creates. If you do not specify a version number for the file in 
your domain definition, the new file does not replace the old one but is 
assigned the next higher version number (non-RSTS/E systems only). 



5-50 Commands, Statements, and Definition Clauses 



DEFINE FILE 
Continued 



MAX 

Causes DATATRIEVE to create a fixed-length RMS file for a domain whose 
record definition contains an OCCURS... DEPENDING clause. The length of 
every record in the data file has the maximum possible size, as determined by 
the value of the max argument in the OCCURS... DEPENDING clause: 

OCCURS min TO max TIMES DEPENDING ON field-name 

Each record can then store the maximum number of items in the list defined 
by the OCCURS... DEPENDING clause. If you omit this argument, 
DATATRIEVE does not create a file with fixed-length records of the maxi- 
mum possible size. The size of each record is determined when you store it. If 
you define the file to be a sequential file, you cannot increase the size of a 
record to include more list items than you first stored in the record. 

KEY = field-name 

Causes DATATRIEVE to create an RMS indexed sequential file and specifies 
a field in the domain's record definition to be used as an index key for the 
domain's data file. When you omit this clause, DATATRIEVE creates an 
RMS sequential file. The first key field specified in the DEFINE FILE com- 
mand is the primary key, and all subsequent ones are alternate keys. If you 
specify more than one KEY clause, use a comma (,) to separate each clause 
from the next. If you are defining a file for a hierarchical record, do not make 
a list field the primary key. 

(NO) CHANGE 

Determines whether or not you can modify the content of the associated key 
field. See Tables 5-3 and 5-4 for defaults and allowed combinations of key field 
attributes. 

(NO) DUP 

Determines whether or not you can assign the same value to the specified key 
fields of two or more records. See Tables 5-3 and 5-4 for defaults and allowed 
combinations of key field attributes. 

Table 5-3: Default Values for KEY fields 



Primary 
Key 


Alternate 
Key(s) 


NO CHANGE 
NO DUP 


CHANGE 
DUP 
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Table 5-4: Allowed Combinations of Key Field Attributes 



Combinations 


Key Type 


Primary 


Alternate 


CHANGE + DUP 
CHANGE + NO DUP 
NO CHANGE + DUP 
NO CHANGE + NO DUP 


Not allowed 
Not allowed 
Allowed 
Default 


Default 
Not allowed 
Allowed 
Allowed 



Restrictions 

• To define a data file for an RMS domain, you must have A (ACCESS) privilege 
for the domain and E (EXECUTE) privilege for the record. 

• You cannot assign the CHANGE attribute to a primary key. See Table 5-4 for 
the allowed combinations of key field attributes. 

• You cannot designate a list field as the primary key when defining a file for a 
hierarchical record. 

• The domain specified in the command must be an RMS domain, and not a view 
domain, DBMS- 11 domain, or port. 

Results 

• If you do not include a KEY clause, DATATRIEVE creates an RMS sequential 
data file for the specified domain. If you include one or more KEY clauses, 
DATATRIEVE creates an RMS indexed sequential data file for the domain. 

• The file specification for the RMS file created by this command is the same as 
the file specification defined in the DEFINE DOMAIN command that defined 
the domain name. If the domain definition omits a field in the file specification, 
DATATRIEVE uses the following defaults: 



Field 


Default 


dev: 


SY: (the system device) 


[UIC/PPN] 


Your default UIC/PPN 


file-name 


No default 


•type 


.DAT 


;ver 


1 or next higher version number 




(non-RSTS/E systems only) 
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• If you omit the ALLOCATION = n clause, DATATRIEVE sets the initial disk 
space allocation for the data file to zero blocks. When you store records in the 
data file, RMS automatically extends the data file according to the cluster size 
on RSTS/E systems and the default extension size on RSX systems. 

• If the record definition associated with the specified domain contains no 
OCCURS... DEPENDING clause, DATATRIEVE creates a data file with a 
fixed-length record format. 

• If the record definition associated with the specified domain contains an 
OCCURS.. .DEPENDING clause, DATATRIEVE creates a data file as follows: 

- If the clause does not include the MAX argument, DATATRIEVE creates a 
file with a variable-length record format. 

- If the clause includes the MAX argument, DATATRIEVE creates a data file 
with a fixed-length record format. 

• If you include the SUPERSEDE argument and the file specification in the 
domain definition specifies a version number, DATATRIEVE deletes any exist- 
ing data file having that file specification and version number and replaces it 
with the new data file created by the DEFINE FILE command. The new file 
has the same file specification including version number, if applicable, as that 
of the deleted file. 

Usage Notes 

• If you define a sequential file, you cannot delete records from it with the 
ERASE statement. You can, however, change the value of any field in a record 
in a sequential file. 

• If you define an indexed sequential file, you can delete records from it with the 
ERASE statement. You cannot, however, change the value of the primary key 
field of a record or the value of any secondary key field with the NO CHANGE 
attribute. 

• If you change the size of a record, you need to define a new file to agree with the 
new record definition. Otherwise, you receive an error message indicating "bad 
record size" when you try to ready the domain. 

• If you define a sequential file for a hierarchical record(OCCURS... DEPEND- 
ING) and do not include a MAX clause, you cannot extend the length of the list 
without defining a new file. 

• If you define an indexed sequential file for a hierarchical record 
(OCCURS.. .DEPENDING) and do not use MAX, you can extend the length of 
the list. 

• See Chapter 6 in the DATATRIEVE-11 User's Guide for more information on 
defining data files. 
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Examples 

Define an indexed file for the domain PHONES. Use the field NAME as the pri- 
mary key: 

DTR > DEFINE FILE FOR PHONES KEY = NAME© 
DTR > 

Define a sequential file for the domain FAMILIES: 

DTR > DEFINE FILE FOR FAMILIES© 
DTR> 

Define a new indexed file for the domain YACHTS. Use the group field TYPE as 
the primary key, and allow duplicate values for this key. This command replaces 
the previous data file for YACHTS: 

DTR > DEFINE FILE FOR YACHTS SUPERSEDE KEY = TYPE (DUP)© 
DTR> 
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5.1 6 DEFINE PORT Command 

Function 

Enters the definition of a DATATRIEVE port in your current dictionary and cre- 
ates an access control list (ACL) for the port. 

Format 



DEFINE PORT port-name [USING] record-name ; 



Arguments 

port-name 

Is the name of the port being defined. The name of the port cannot duplicate 
the name of any other object in the same dictionary. 

record-name 

Is the name of the record definition to be associated with the port. The name 
of the record cannot duplicate the name of any other object in the same 
dictionary. 

; (semicolon) 

Ends the port definition. 

Restrictions 

• Do not use a DATATRIEVE keyword as the name of a port or as the name of 
the record definition associated with the port. 

• You cannot use a DEFINE PORT command as part of a compound statement. 

• You cannot invoke a procedure in a port definition. 

• You must enter the port definition in your current dictionary before using the 
port definition to transfer data between DATATRIEVE and your application 
program. 

Results 

• DATATRIEVE prompts you with the DFN> prompt until you type a semico- 
lon and press RETURN or until it detects a syntax error. If you make a syntax 
error, DATATRIEVE returns to command level (indicated by the DTR> 
prompt) without entering the port definition in the dictionary. 

• DATATRIEVE enters the domain definition in your current dictionary and 
creates an access control list (ACL) for the domain by entering a UIC/PPN in 
the ACL with full access privileges (RWMEC). 



Commands, Statements, and Definition Clauses 5-55 



DEFINE PORT 

Continued 



Usage Notes 

• Before you can use the port, you must enter the record definition associated 
with the port in the data dictionary with the DEFINE RECORD command (see 
Section 5.18). 

• Use the SHOW command to display the definition of the port on your terminal. 

• Use the SHOW DOMAINS command to display the names of all the ports in 
your current dictionary. 

• See the DATATRIEVE-11 Call Interface Manual for information about using a 
port to transfer data between DATATRIEVE and your application program: 

Example 

Define a port for transferring records between the YACHTS domain and an 
application program. 

DTR> DEFINE PORT YPORT USING YACHT! (ret) 
DTR> 
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5.1 7 DEFINE PROCEDURE Command 

Function 

Enters a procedure definition in your current dictionary and creates an access 
control list (ACL) for the procedure. 

Format 

DEFINE PROCEDURE procedure-name 
END-PROCEDURE 



Arguments 

procedure-name 

Is the name of the procedure you want to define. That procedure name cannot 
duplicate the name of any other object in the same dictionary. 

END_PROCEDURE 

Ends the procedure. 

Restrictions 

• You must enter the DEFINE PROCEDURE command at DATATRIE VE com- 
mand level (indicated by the DTR> prompt). It cannot be part of a 
DATATRIE VE statement. 

• To define a procedure, you must have operating system write access privilege 
to the dictionary file. 

• The procedure being defined cannot contain any DEFINE commands. 
Results 

• After you type DEFINE PROCEDURE procedure-name and press RETURN, 
DATATRIE VE displays the DFN> prompt. You then define the procedure by 
entering commands and statements in response to this prompt. DATATRIEVE 
continues to prompt with the DFN> prompt until you type 
END_PROCEDURE to end the definition. 

• DATATRIEVE enters the procedure in your current dictionary and creates an 
access control list (ACL) for the domain by entering aUIC/PPN in the ACL 
with full access privileges (RWMEC). 
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Usage Notes 

• To invoke a procedure during an interactive DATATRIEVE session, enter a 
colon followed by the name of the procedure. You can invoke a procedure in 
response to any DATATRIEVE prompt, except those of ADT, Guide Mode, and 
the Editor. You can also invoke procedures in the midst of input lines. 

• To invoke a procedure with an invocation command line from your operating 
system level, type the command you use to invoke DATATRIEVE, a colon, and 
the procedure name. 

• The DEFINE PROCEDURE command creates procedures. To modify a proce- 
dure after you have stored it in the dictionary, use the DATATRIEVE Editor. 
When you exit from the Editor, DATATRIEVE deletes the old procedure defi- 
nition and stores the updated procedure definition in your current dictionary. 
See Chapter 17 of the DA TA TRIEVE-1 1 User's Guide and Section 5.25 of this 
manual for information on using the DATATRIEVE Editor. 

• When you invoke a procedure from a REPEAT or FOR loop, enclose the proce- 
dure in a BEGIN-END block to ensure that DATATRIEVE executes all the 
statements in the procedure each time through the loop. A procedure invoked 
in this way cannot include any commands or FIND, SELECT, DROP, or 
RELEASE statements. 

• For more information on procedures, see Chapter 9 of the DATATRIEVE-11 
User's Guide. 
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Examples 

Define a procedure to set your current dictionary to DEMO.DIC: 

DTR > DEFINE PROCEDURE DEMO© 

DFN > SET DICTIONARY DB2 : [53 >27]DEM0.DI C© 

DFN> SHOW DICTIONARY© 

DFN> END_ PROCEDURE© 

DTR > : DEMO© 

The default dictionary is DB2 : C 53 ,27 UDEMO . D I C 
DTR> 



Define a procedure that displays a group of boats with a price less than a figure 
you supply when you run the procedure. 

DTR > DEFINE PROCEDURE PR I CE_L I ST© 
DFN > READY YACHTS© 

DFN > PRINT SKIP* COL 20* "*** Price List of YACHTS ***"♦ SKIP© 

DFN> FOR YACHTS WITH PRICE NE AND PRICE LE **"the c e i 1 i r. 3 price 

DFN > PRINT BOAT© 

DFN > PRINT SKIP* COL 10* "See any thin* interesting?"© 

DFN > END_ PROCEDURE© 
DTR > : PRICE-LIST© 

*** Price List of YACHTS *** 
Enter the ceiling price: 5 » 



LENGTH 
OVER 



MANUFACTURER 


MODEL 


RIG 


ALL 


DISPLACEMENT 


BEAM 


PRICE 


CAPE DORY 


TYPHOON 


SLOOP 


19 


1 


♦ 900 


OB 


$4 


,295 


VENTURE 


21 


SLOOP 


21 


1 


»500 


07 


$2 


»823 


VENTURE 


*7 *? 


SLOOP 




2 


* 


07 


$3 


»5B4 


WINDPOWER 


IMPULSE 


SLOOP 


IB 




650 


07 


$3 


1 5 



See anything interesting? 

DTR > 



Use an invocation command line to invoke the DEMO procedure: 

$ DTR : DEMO© 

The default dictionary is DB2: [53 >273DEM0.DIC 
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5.1 8 DEFINE RECORD Command 



Function 

Enters a record definition in your current dictionary and creates an access con- 
trol list (ACL) for the record definition. 

Format 



DEFINE RECORD record -name [USING] 
ALLOCATION IS 



MAJOR-MINOR 
ALIGNED-MAJOR-MINOR 
LEFT-RIGHT 



level-number-1 field-name-1 [field-definition-1] . 
[level-number-2 field-name-2 field-definition-2 .] 



Arguments 

record-name 

Is the name of the record being defined. The record name cannot duplicate the 
name of any other object in the same dictionary. 

ALLOCATION 

Specifies the type of word-boundary alignment DATATRIEVE uses when 
storing records in the data file. It also controls the way DATATRIEVE 
retrieves data from data files created by user programs or other application 
software. The default allocation is LEFT.RIGHT. See the PDP-11 COBOL 
Language Reference Manual or the COBOL-81 Language Reference Manual 
for more information on word-boundary alignment and allocation of fill bytes. 
See Section 5.6 in this manual for more information on the ALLOCATION 
clause. 

level-number 

Is the level number for the field in the record definition. It indicates the rela- 
tionship of the field to the other fields in the record definition. 

field-name 

Is the name of the field. Every field must have a name. The keyword FILLER 
is a special field name that can be repeated at the same level in the record 
definition. 
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field-definition 

Is a field definition. A record definition must contain at least one field defini- 
tion. Elementary fields must have at least one field definition clause. Group 
fields do not have to have any field definition clauses. 

. (period) 

Ends the field definition. 
; (semicolon) 

Ends the record definition. 
Restrictions 

• You cannot invoke a procedure in a record definition. 

• The level number must be an integer between 1 and 65. 

• A record definition must contain the field definition of at least one elementary 
field. 

• The field definition of an elementary field must contain at least one field defini- 
tion clause. 

• No field name should duplicate the domain name. 
Results 

• DATATRIEVE prompts with the DFN> prompt until you type a semicolon 
and press return, or until it detects a syntax error. If you make a syntax error, 
DATATRIEVE returns to command level (indicated by the DTR> prompt) 
without creating the record definition. 

• When you end the record definition, DATATRIEVE displays a message on your 
terminal that indicates the length of the new record: 

DTR> DEFINE RECORD A_REC USING© 

DFN> 01 TOP ♦ (ret) 

DFN> 03 CHAR PIC }<♦© 

DFN> 03 NUM USAGE IS COUP.© 

DFN> 5© 

[Record A_REC is 4 bytes Ion <J] 
DTR > 

• DATATRIEVE enters the record definition in your current dictionary and cre- 
ates an ACL for the record definition by entering a UIC/PPN with full access 
privileges of RWMEC. 
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Usage Notes 

• The DEFINE RECORD command creates records. To modify or replace a 
record after you have stored it in the dictionary, use the DATATRIE VE Editor. 
When you exit from the Editor, DATATRIEVE deletes the old record definition 
and stores the updated record definition in your current dictionary. See 
Chapter 17 of the DA TA TRIEVE-1 1 User's Guide and Section 5.25 of this 
manual for information on using the DATATRIEVE Editor. 

• If you change a record definition, you may not be able to use old data files. If the 
new record definition is not the same length, or if the new field definitions 
change to data types incompatible with the previous definition, you have to 
redefine and restructure the data as described in Chapter 16 of the 

DA TA TRIEVE-1 1 User's Guide. 

The safest method for changing record definitions is to define a new domain 
and a new file to accompany the new record definition, and use the STORE 
statement to transfer the values from the data file of the old domain to the data 
file of the new domain. 

Examples 

Define the record PHONE_REC: 

DTR > DEFINE RECORD PHONE-REC USING© 
DFN > 01 PHONE ♦ (RET) 



DFN> 02 NAME PIC X<20>.© 

DFN > 02 NUMBER PIC 9(7) ED IT-STRING IS XXX-XXXX,© 

DFN > 02 LOCATION PIC X(9).© 

DFN > 02 DEPARTMENT PIC XX.© 



DFN > 5 (ret) 

[Record PH0NE_REC is 38 bytes lonsf,3 
DTR > 

Define the record FAMILY: 

DTR> DEFINE RECORD FAMILY USING© 
DFN> 01 FAMILY ♦(ret) 



DFN > 03 PARENTS ♦ © 

DFN > OS FATHER PIC X(10).© 

DFN> OS MOTHER PIC X(10),© 

DFN > 03 NUMBER-KIDS PIC 99 EDIT-STRING IS 29,© 

DFN > 03 KIDS OCCURS TO 10 TIMES DEPENDING ON NUMBER_K I DS . © 
DFN > OB EACH_KID,© 

DFN > 09 KID_NAME PIC X<10) QUERY-NAME IS KID, © 

DFN > 09 AGE PIC 99 EDIT-STRING IS Z9,© 



DFN > ",© 

[Record FAMILY is 142 bytes Ion a, 3 
DTR > 
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5.1 9 DEFINE TABLE Command 



Function 

Enters a dictionary table in your current dictionary and creates an access control 
list (ACL) for the table. 



Format 



DEFINE TABLE table-name 



"code-1" 
code-1 

"code-2" 
code-2 



"translation-1 " 
translation-1 

"translation-2" 
translation-2 



ELSE 
END_TABLE 



"translation-n' 
translation-n 



Arguments 

table-name 



Is the name of the dictionary table being denned. The name of the table can- 
not duplicate the name of any other object in the same dictionary. 

"code" : "translation" 
code : translation 

Are code-translation pairs. You must separate the code and its translation 
with a colon. The comma after each pair is required except for the last pair if 
there is no ELSE clause. If the code or translation string conforms to the rules 
for DATATRIEVE names, you do not have to use quotation marks. 
DATATRIE VE converts lowercase letters in unquoted code or translation 
strings to uppercase letters. 

If the code or translation string does not conform to the rules for 
DATATRIEVE names (especially if it contains spaces), or if you want to pre- 
serve lowercase letters, you must use quotation marks and follow the rules for 
character string literals (see Chapter 2). 



Commands, Statements, and Definition Clauses 5-63 



DEFINE TABLE 

Continued 



ELSE "translation" 
translation 

Is the translation to be used if you specify a code not denned in the dictionary 
table. The rules for specifying this translation string are the same as those for 
codes and translations. 

END _TABLE 

Ends the dictionary table definition. 

Restrictions 

• You cannot include the invocation of a procedure (:procedure-name) in a dic- 
tionary table definition. 

• The name of a dictionary table cannot duplicate a DATATRIEVE keyword. 
Results 

• DATATRIEVE prompts with the DFN> prompt until you end the table defini- 
tion with the keyword END_TABLE. 

• DATATRIEVE enters the dictionary table in your current dictionary and cre- 
ates an ACL for the table by entering a UIC/PPN with full access privileges of 
RWMEC. 

Usage Notes 

• When you invoke a dictionary table with an IN or VIA clause, the table is 
loaded into your workspace and remains available to you until you remove it 
with a RELEASE command or exit from DATATRIEVE. Changing your cur- 
rent dictionary does not affect dictionary tables loaded in your workspace. 

• Use the SHOW READY command to display the names of dictionary tables 
loaded in your workspace. 

• DATATRIEVE uses a default edit string of 10 characters when it displays the 
translation string on your terminal or writes the value to another output 
device. You can specify an edit string each time you use a VIA value expres- 
sion. For example: 

DTR> PRINT "CE" VIA DE PI-TABLE© 
Commercial 

DTR> PRINT "CE" VIA DEPT_TABLE USING T<25)© 
Commercial Engineering 

DTR> 

• You can specify a column header each time you use a VIA value expression. 

• For more information on using dictionary tables, see Chapter 13 of the 
DA TA TRIEVE-1 1 User's Guide. 
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• The definition of a dictionary table differs from the definitions of domains and 
records because it contains values, not just a data description. 

• To modify a dictionary table, use the DATATRIEVE Editor to modify, delete, 
or add codes and translations. When you exit from the Editor, DATATRIEVE 
deletes the old table definition and stores the updated definition in your cur- 
rent dictionary. See Chapter 17 of the DA TA TRIEVE-1 1 User's Guide and 
Section 5.25 of this manual for information on using the DATATRIEVE 
Editor. 

Examples 

Define a table of department codes and display the translation for the RD code 
string: 

DTR> DEFINE TABLE DEPT_TABLE© 

DFN> CE : "Commercial En 3 i n e e r i n sf " *© 

DFN > PE : "Plant Engineering"*© 

DFN> CS : "Customer Support"*© 

DFN> RD : "Research and Development" i© 

DFN > SD : "Sales Department"*© 

DFN> ELSE "UNKNOWN DEPARTMENT "© 

DFN> END_TABLE© 

DTR> PRINT "RD" MIA DEPT-TABLE USING T(25)© 
Research and Development 

DTR> 

Define a table with a translation for each possible rig: 

DTR > DEFINE TABLE R I G_TABLE© 
DFN > SLOOP : " ONE MAST"*© 

DFN > KETCH : "TWO MASTS* BIG ONE IN FRONT"*© 

DFN > YAWL : "SIMILAR TO KETCH"*© 

DFN > MS : "SAILS AND A BIG MOTOR"*© 

DFN> ELSE "SOMETHING ELSE"© 

DFN > END_TABLE© 

DTR > PRINT "KETCH" VIA R I G_TABLE USING TOO)© 
TWO MASTS* BIG ONE IN FRONT 

DTR > 
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5.20 DEFINEP Command 

Function 

Adds an entry to the access control list (ACL) for a dictionary object. 



Format 



DEFINEP object-name 


(passwd) 
(*) 


PW, new-passwd 
sequence-number, ^ m ^ 


, priv 



Arguments 

obj-name 

Is the name of the domain, record, procedure, or table whose ACL you want to 
modify. 

(passwd) 
(*) 

Is the password necessary to gain C (control) access to the dictionary object or 
an asterisk enclosed in parentheses (*). If you specify a password, you must 
enclose it in parentheses. If you specify (*), DATATRIEVE prompts for the 
password, but does not print your response on the terminal. If you omit this 
argument, DATATRIEVE uses your log-in UIC/PPN to verify that you have 
C (control) access privilege. 

seq-no 

Is the sequence number of the entry to be added to the ACL. This argument 
must be an unsigned integer and must be followed by a comma (,). 

PW, new-passwd 
UIC,[m,n] * 

Specifies the lock type and key for the entry. If the lock type is PW, specify a 
1- to 10-character password. If it is UIC, specify a UIC/PPN, enclosed in 
square brackets. You must put a comma after the lock type and another 
comma after the key. 

priv 

Is a letter or string of letters indicating the type of access privilege to be 
granted. You can also use a space enclosed in quotation marks to indicate 
that the user is not granted any access privileges. Table 5-5 lists access privi- 
lege codes. 
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Table 5-5: Access Control Privilege Codes 



Letter 


Privilege 


R 


Read 


E 


Execute or Extend 


M 


Modify 


W 


Write 


C 


Control 




No privilege 



Restriction 

You must have C (control) access privilege to the dictionary object. 
Result 

DATATRIEVE creates an entry in the ACL. Depending on the sequence number 
you supply, DATATRIEVE may change the sequence number of other entries in 
the ACL: 

• If the sequence number already exists in the ACL, DATATRIEVE adds the 
entry immediately before the existing entry with the same number and 
increases by one the sequence number of all entries after the new entry. 

• If the sequence number is greater than the last sequence number plus one, 
DATATRIEVE ignores your sequence number and adds the entry to the end of 
the ACL. Its sequence number becomes the next sequential number in the 
ACL. 

• You can specify more than one privilege with a string of letters, in any order, 
such as RWM for read, write, and modify access. Do not put spaces between let- 
ters in a string of letters. 
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Usage Notes 

• When designing an ACL, put entries with the most specific user identification 
criteria at the top of the list and entries with the most general user identifica- 
tion criteria at the bottom of the list. When you access a dictionary object, 
DATATRIEVE begins at the top of the list and applies the first entry in which 
all the user identification criteria apply to you. 

If, for example, the first ACL entry specifies a number as the only user identifi- 
cation criterion in the entry and you are using that number, you match all the 
user identification criteria for that entry. Your UIC/PPN and any password 
you supply do not matter. That you also match other entries in the ACL is of no 
consequence; your other user identification characteristics would not be 
checked against other ACL entries until you used another number to access 
the dictionary object in question. 

• You can enter user identification criteria and privilege specifications in any 
order. You need not put the user identification criteria before the privilege 
specifications. 

• To avoid errors when making an addition, display on your terminal a copy of 
the current ACL with the SHOWP command before issuing the DEFINEP 
command. See the description in this chapter of the SHOWP command. 
Because DATATRIEVE can change sequence numbers, a new entry can affect 
the numbering of other ACL entries. 

• To remove an entry from an ACL, use the DELETEP command (see Section 
5.23). 

• Chapter 20 of the DA TA TRIEVE-1 1 User's Guide discusses the use of ACLs. 
Example 

Define an ACL entry for a dictionary that uses all the user identification criteria 
and all the privilege specifications. Use the SHOWP command to show the new 
access control list: 

DTR > DEFINEP MONTHLY.DATA 1>PW> " GELSEY " * "C "(RET) 
DTR > DEFINEP M0NTHLY_DATA 2>UIC» " C 150 »*] " t "R"(reT) 
DTR > SHOWP MONTHLY_DATA(RET) 

1 »PW t " GELSEY " t "C" 

2 »UIC * C 150 »*] t " R " 

DTR > 
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5.21 DELETE Command 

Function 

Deletes a dictionary object and its associated access control lists (ACLs) from 
your current dictionary. 

Format 



DELETE object-name ; 



Arguments 

object-name 

Is the name of the object you want to remove from the dictionary. 
; (semicolon) 

Ends the DELETE command. 
Restrictions 

• You must have C (control) access privilege to the dictionary object before you 
can delete it. 

• You cannot delete a dictionary with the DELETE command, even if the 
dictionary is empty. To delete a dictionary, you must use the operating 
system DELETE command. See the RSTS/E DCL User's Guide or the 
RSX-11M/M-PLUS Command Language Manual, as appropriate. 

Results 

• If you specify the name of a domain definition or a record definition in the 
DELETE command, DATATRIEVE deletes the definition of the domain or 
record, but does not delete the associated record or domain definition or the 
associated data file. 

• A readied domain is not affected by the deletion of the domain definition or the 
definition of its associated record. However, after you release a domain whose 
definition or record definition has been deleted from the dictionary, you cannot 
ready the domain again. 

• If the dictionary object you specify in a DELETE command is a procedure, 
DATATRIEVE deletes the procedure from the data dictionary. You cannot 
invoke a procedure after it has been deleted from the dictionary. 

• If the dictionary object you specify in a DELETE command is a dictionary 
table, DATATRIEVE deletes the dictionary table from the data dictionary. A 
dictionary table loaded in your workspace remains there until you release it, 
even if you delete its definition. However, after you have released the table, it 
cannot be loaded again. 

• When DATATRIEVE deletes a dictionary object, it also deletes the ACL asso- 
ciated with the object. 
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Examples 

Delete a procedure from your current dictionary: 

DTR > SHOW HELO© 
PROCEDURE HELO 

PRINT "Good morn in 5" 
END-PROCEDURE 

DTR > DELETE HELO 5 (ret) 
DTR > SHOW HELO© 

"HELO" has not been defined in the dictionary 
DTR > 



Delete the domain and record definitions of a readied domain: 

DTR> SHOW YACHTS-SEQ© 
DOMAIN YACHTS-SEQ 

USING Y ACHT_SEQ_REC ON YACHTS ♦ DAT 5 
DTR > READY YACHTS-SEQ© 
DTR > FIND YACHTS-SEQ© 
[113 records founds 
DTR > DELETE YACHTS-SEQ© 
DTR> SHOW YACHT-SEQ© 

"YACHTS-SEQ" +ias not been defined in the dictionary 
DTR> DELETE YACHT_SEQ_REC (ret) 
DTR > SHOW YACHT_SEQ_REC© 

" YACHT_SEQ_REC" has not been defined in the dictionary 
DTR> SHOW READY© 
Ready domains: 

Y ACHTS-SEQ : RMS INDEXED t PROTECTED READ 



DTR > SHOW FIELDS© 
YACHTS-SEQ 
BOAT 

TYPE [Indexed field] 

MANUFACTURER (BUILDER) [Character strinS» indexed Key] 

MODEL [Character strinsft indexed Key] 

SPECIFICATIONS (SPECS) 

RIG [Character string] 

LENGTH _O l ,'ER_ ALL (LOA) [Character string] 

DISPLACEMENT (DISP) [Number] 
BEAM [Number] 
PRICE [Number] 

DTR > FINISH YACHTS-SEQ© 
DTR > SHOW READY© 
No Domains Readied 
DTR> SHOW YACHTS-SEC© 

"YACHTS_SEO" has not been defined in the dictionary 
DTR > SHOW YACHT-SEO-REC© 

" YACJHT_SEQ_REC" has not been defined in the dictionary 
DTR> SHOW FIELDS© 

No Domains Readied or Global Variables Declared 
DTR> 
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5.22 DELETEP Command 

Function 

Deletes an entry from the access control list (ACL) of a dictionary object. 
Format 



DELETEP object-name sequence-number 



Arguments 

object-name 

Is the name of the dictionary object whose ACL you want to change, 
sequence-number 

Is a nonzero integer indicating the entry's position in the ACL. 
Restrictions 

• You must have C (control) access privilege to the dictionary object before you 
can delete an entry from its ACL. 

• You can delete only one ACL entry at a time with the DELETEP command. 
Results 

• DATATRIE VE deletes the entry with the specified sequence number from the 
ACL of the dictionary object. 

• If the sequence number you specify is greater than the number of entries in the 
ACL, DATATRIE VE displays the message "Protection table element doesn't 
exist" and does not delete anything. 

• When you remove an entry from any position in the ACL, except the last one, 
DATATRIEVE renumbers the remaining entries so that the sequence num- 
bers begin at one and increase in steps of one. 

Usage Notes 

• To ensure that you delete the correct entry, display the ACL on your terminal 
with the SHOWP command before you enter the DELETEP command. 

• If you need to remove many entries from a long ACL, begin with the entries at 
the bottom of the list and work your way toward the top. This method preserves 
the original sequence numbers of the entries you want to remove. If you start 
removing entries at the top of the list, every time you remove an entry the 
numbers of all the other ones you want to remove change. 
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• DATATRIEVE allows you to delete the last ACL entry having C access, so be 
careful when deleting ACL entries. The only way you can gain access to a dic- 
tionary object that does not allow you C access is to log into a privileged 
account from the system command level before invoking DATATRIEVE. A 
privileged account automatically grants you C (control) access. 

Examples 

Show the ACL of the YACHTS domain and delete an entry from it: 

DTR > SHOWP YACHTS© 

1 f UIC , [32 t 56] i " RWMEC " 

2 t UIC t El 50 t 150] t "R" 

DTR > DELETEP YACHTS 2© 
DTR > SHOWP YACHTS© 

1 t UIC t 132 t 563 t "RWMEC" 

DTR > 

See Chapter 20 of the DA TA TRIEVE-1 1 User's Guide for other examples of 
working with ACLs. 



5-72 Commands, Statements, and Definition Clauses 



DISPLAY 



5.23 DISPLAY Statement 

Function 

Displays on your terminal the value of a single DATATRIEVE value expression. 
The value displayed is not formatted by any edit string associated with the value 
expression. 

Format 



DISPLAY value-expression 



Arguments 

value-expression 

Is a DATATRIEVE value expression. 
Restrictions 

• To display the value of a field in a record, the domain containing that record 
must be readied for read, write, or modify access. If you specify a field name 
from a domain readied for extend access, DATATRIEVE displays an error mes- 
sage. 

• You must establish a valid context for the record or records containing the field 
value or values you want to display. See Chapter 12 in the DATATRIEVE -11 
User's Guide for information on record context. 

Results 

• DATATRIEVE displays the current, unformatted value of the specified value 
expression, ignoring the COLUMNS-PAGE setting and any edit string associ- 
ated with the value. 

• If the specified value expression is a group field, DATATRIEVE concatenates 
the values of the elementary fields and leaves no spaces between fields except 
the blanks that pad character string fields. 

Examples 

Declare a numeric variable with a money edit string, assign it a value, and use 
the PRINT and DISPLAY statements to display the value: 

DTR > DECLARE SALARY PIC Z(5)9U99 EDIT.STRING $$$$$$. 99 , (ret) 
DTR> SALARY = 1 5753 . E7(ret) 
DTR > PRINT SALARY© 

SALARY 

$15753.67 

DTR> DISPLAY SALARY© 
DISPLAY: 15753. B7 
DTR > 
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Declare the SALARY variable as a character variable, assign it a value, and use 
the PRINT and DISPLAY statements to display the value: 

DTR > DECLARE SALARY PIC X(15) ( ® 
DTR> SALARY = " MUCH TOO LOW"© 
DTR > PRINT SALARY® 

SALARY 

MUCH TOO LOW 

DTR> DISPLAY SALARY© 
DISPLAY: MUCH TOO LOW 
DTR > 

Display the group fields TYPE, SPECS, and BOAT of a record in the YACHTS 
domain: 

DTR > READY YACHTS © 

DTR > FIND FIRST 1 YACHTS© 

CI Record found] 

DTR > select; PRINT© 

LENGTH 
OVER 

MANUFACTURER MODEL RIG ALL WEIGHT BEAM PRICE 

ALBERG 37 MK II KETCH 37 20 tOOO 12 *3S>951 

DTR > DISPLAY TYPE© 
DISPLAY: ALBERG 37 MK II 
DTR > DISPLAY SPECS© 
DISPLAY: KETCH 37 200001236951 
DTR> DISPLAY BOAT© 

DISPLAY: ALBERG 37 MK II KETCH 37 200001236951 
DTR > 
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5.24 DROP Statement 

Function 

Removes the selected record from a collection, but does not remove that record 
from the data file in which it resides. 

Format 



DROP [collection-name] 



Arguments 

collection-name 

Is the name of a collection. If you do not specify a collection, DATATRIEVE 
removes the selected record in the most recent single record context. 

Restrictions 

• You must use the SELECT statement to establish a selected record in a collec- 
tion before using a DROP statement. DATATRIEVE displays the message "No 
collection with selected record for DROP" if you have no established collec- 
tions, or if no collection has a selected record. 

• You cannot drop a record that has been erased or dropped. If you have already 
removed the selected record, DATATRIEVE displays a message and the DROP 
statement does not execute. 

• You can use the DROP statement only to remove records from collections. 
DATATRIEVE displays the message "DROP can only be used for collections" if 
you try to use DROP to remove anything other than a record selected from a 
collection. 

Results 

• Once a record has been dropped from a collection, it is no longer available to 
you in the collection. The dropped record is not erased from the data file. You 
can retrieve it again by forming a record stream or another collection that con- 
tains it. 
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• When you enter a DROP statement without specifying a collection name, 
DATATRIEVE drops the selected record in the nearest single record context: 

- If the CURRENT collection has a selected record, DATATRIEVE drops it 
from the CURRENT collection. 

- If the CURRENT collection has no selected record but other named collec- 
tions do, DATATRIEVE drops the selected record from the most recently for- 
med of those collections. 

- If the selected record in the nearest single record context has been pre- 
viously dropped, DATATRIEVE displays the message "No collection with 
selected record for DROP" and the DROP statement does not execute. 

• When you specify a collection name, DATATRIEVE drops the selected record 
in the specified collection. If the named collection has no selected record, or if 
the selected record has been erased, DATATRIEVE displays an error message 
and does not execute the DROP statement. 

Usage Notes 

• Use the DROP statement to refine a collection until it contains exactly the 
records you want. 

• Before dropping a selected record in the nearest single record context, display 
the record on your terminal by typing PRINT and pressing RETURN. 

Examples 

Form a collection, select a record, and drop the selected record. PRINT state- 
ments show the established collection before and after the DROP statement 
executes: 

DTR> READY YACHTS© 

DTR > FIND A IN YACHTS WITH BUILDER = "AMERICAN "(RET) 
L 2 records found] 
DTR> PRINT A (ret) 







LENGTH 












OVER 








MANUFACTURER MODEL 


RIG 


ALL 


WEIGHT 


BEAM 


PRICE 


AMERICAN 26 


SLOOP 


26 


4 »000 


08 


$9 ,895 


AMERICAN 2S-MS 


MS 


26 


5 >500 


08 


$18 ,895 



DTR > SELECT© 
DTR> DROPdD 
DTR > PRINT A (ret) 



MANUFACTURER MODEL RIG 
AMERICAN 26-MS MS 



LENGTH 
OVER 
ALL 

26 



WEIGHT BEAM PRICE 
5*500 08 $18*895 



DTR > 
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Store a record in YACHTS, form a series of collections, and use the SELECT, 
DROP, ERASE, and PRINT statements to illustrate the difference between the 
DROP and ERASE statements: 



DTR > SET NO PROMPT© 

DTR > READY YACHTS WRITE© 

DTR > STORE YACHTS USING BUILDER = "AMERICAN"© 
DTR > FIND A IN YACHTS WITH BUILDER = "AMERICAN"© 
C3 records found] 
DTR > PRINT A© 

LENGTH 



MANUFACTURER 

AMERICAN 
AMERICAN 
AMERICAN 



MODEL 



RIG 



OYER 
ALL 



WEIGHT BEAM PRICE 



2G-MS 





SLOOP 26 4,000 08 $9,895 

MS 26 5*500 08 $18,895 



DTR > SELECT FIRST 5 PRINT© 



MANUFACTURER MODEL 

AMERICAN 

DTR> DROP© 
DTR > PRINT A© 

MANUFACTURER MODEL 



AMERICAN 
AMERICAN 



26 

2S-MS 



LENGTH 
OVER 

RIG ALL WEIGHT BEAM PRICE 




LENGTH 
OVER 

RIG ALL WEIGHT BEAM PRICE 

SLOOP 26 4*000 08 $9,895 

MS 26 5,500 08 $18,895 



DTR > FIND B IN YACHTS WITH BUILDER = "AMERICAN"© 
C3 records found] 
DTR> PRINT B© 



MANUFACTURER 

AMERICAN 
AMERICAN 
AMERICAN 



MODEL 



26 

26-MS 



RIG 



LENGTH 
OVER 
ALL 



WEIGHT BEAM PRICE 



KETCH 00 

SLOOP 26 4,000 08 $9,895 

MS 26 5,500 08 $18,895 



DTR > SELECT FIRST© 
DTR > ERASE© 
DTR > DROP© 

No collection with selected record for DROP 
DTR > RELEASE A , B© 

DTR > FIND YACHTS WITH BUILDER = "AMERICAN "© 
C 2 records found] 
DTR> PRINT CURRENT© 



(continued on next page) 
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MANUFACTURER 



MODEL 



LENGTH 
OVER 
RIG ALL 



WEIGHT BEAM PRICE 



AMERICAN 
AMERICAN 



2G 

26-MS 



SLOOP 
MS 



26 
26 



4 ,000 

5 , 500 



08 
08 



$9 ,895 
$18 ,895 



DTR > 



Form a collection and use a FOR statement to drop all records in the collection. 
PRINT statements show the established collection and the empty collection after 
the DROP statement: 



DTR > FIND A IN YACHTS WITH BUILDER 
C3 records found] 
DTR > PRINT CURRENT© 



"CHALLENGER "(ret) 



MANUFACTURER 



MODEL 



LENGTH 
OVER 
RIG ALL 



WEIGHT BEAM PRICE 



1 1 $31 ,835 

12 $39,215 

13 $51 ,228 



CHALLENGER 32 SLOOP 32 12*800 

CHALLENGER 35 SLOOP 35 14*800 

CHALLENGER 41 KETCH 41 26*700 

DTR > FOR CURRENT DROP© 
DTR > PRINT CURRENT© 
DTR > 

Form a collection and use the FOR statement to selectively drop records. PRINT 
statements show the established collection and the refined collection: 



DTR > SET NO PROMPT© 

DTR > FIND A IN YACHTS WITH BUILDER 
CON> BUILDER = "AMERICAN"© 
C 5 records found] 
DTR > PRINT A© 



= "CHALLENGER" OR © 



LENGTH 









OVER 








MANUFACTURER 


MODEL 


RIG 


ALL 


WEIGHT 


BEAM 


PRICE 


AMERICAN 


26 


SLOOP 


26 


4 ,000 


08 


$9 ,895 


AMERICAN 


26-MS 


MS 


26 


5 ,500 


08 


$18 ,895 


CHALLENGER 


32 


SLOOP 


32 


12 ,800 


1 1 


$31 ,835 


CHALLENGER 


35 


SLOOP 


35 


14 ,800 


12 


$39 ,215 


CHALLENGER 


41 


KETCH 


41 


26 ,700 


13 


$51 ,228 



DTR> FOR A WITH BUILDER = 
DTR> PRINT A© 



MANUFACTURER 



MODEL 



"CHALLENGER " DROP© 



LENGTH 
OVER 
RIG ALL 



WEIGHT BEAM PRICE 



AMERICAN 
AMERICAN 



26 

26-MS 



SLOOP 
MS 



26 
26 



4 ,000 

5 ,500 



08 $9,895 
08 $18,895 



DTR > 
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Form a collection, select and drop a record, then select the record before the 
dropped record. When you try to select the next record (the record dropped 
previously,) an error message informs you that the selected record has been 
dropped: 

DTR> FIND A IN YACHTS WITH BUILDER = "CHALLENGER" (ret) 
C3 records found! 
DTR > PRINT© 



MANUFACTURER MODEL 

CHALLENGER 32 
CHALLENGER 35 
CHALLENGER 41 

DTR > SELECT 3© 
DTR > DROP© 
DTR> PRINT A (ret) 



MANUFACTURER MODEL 

CHALLENGER 32 
CHALLENGER 35 

DTR > SELECT 2(H) 
DTR > SELECT NEXT© 
Record has been dropped from collection 
Execution failed 
DTR > 

Try to use the DROP statement to remove records from a domain. An error mes- 
sage informs you that you cannot use a domain name in a DROP statement: 

DTR > FOR YACHTS WITH RIG = "SLODP" DROP© 
DROP can only be used for collections 
DTR> 



RIG 



LENGTH 
OVER 
ALL 



WEIGHT BEAM PRICE 



SLOOP 
SLOOP 
KETCH 



32 
35 
41 



12 »800 
14 »800 

28 ,700 



1 1 
12 
13 



$31 »835 
$39 *215 
$51 ,228 



RIG 



LENGTH 
OVER 
ALL 



WEIGHT BEAM PRICE 



SLOOP 
SLOOP 



32 
35 



12 »800 
14 ,800 



1 1 
12 



$31 >835 
$39 >215 
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5.25 EDIT Command 

Function 

Invokes the DATATRIEVE Editor to edit a dictionary object. 
Format 



EDIT object-name 




[ADVANCED] 



Arguments 

object-name 

Is the name of a DATATRIEVE domain, record, procedure, or table definition 
you want to edit. 

(passwd) 
(*) 

Is an asterisk enclosed in parentheses (*) or the password necessary to gain C 
(control) access to the dictionary object. If you specify a password, you must 
enclose it in parentheses. If you specify (*), DATATRIEVE prompts for the 
password, but does not display your response on the terminal. If you omit this 
argument, DATATRIEVE uses your log-in UIC/PPN to verify that you have 
C (control) access privilege to the object you want to edit. 

ADVANCED 

Specifies that you want to edit a domain or record definition. You must 
include this keyword before you can edit a domain or record definition. 

Restrictions 

• You must have W (write) access to your current dictionary before you can use 
the EDIT command. 

• To edit a DATATRIEVE domain, record, procedure, or table definition, you 
must have C (control) access privilege to the dictionary object you want to edit. 

Results 

• When you use the EDIT command, DATATRIEVE invokes the Editor, loads 
the specified definition into the main text buffer of the Editor, and prompts 
with QED>, the editing command mode prompt. You can type any Editor com- 
mand in response to the prompt. Editor commands are summarized in Table 
5-6. 



5-80 Commands, Statements, and Definition Clauses 



EDIT 
Continued 



Table 5-6: Summary of DATATRIEVE Editor Commands 



Command 


Format and Functions 


CTRL/Z 


CTRL/Z 

Ends an editing session and returns you to DATATRIEVE command level 
when typed in response to the QED> prompt. The edited dictionary object 

1 t?^iidvt?& Lilt; ^jit;viuu.o vtJi&iuii. xii nit; \xcx\j<x u.i^Liuiicii i y. vviit;ii uyjjcu 111 

response to the IN> prompt, CTRL/Z exits from insert mode. 


DELETE 


D[ELETE] [range] 

Deletes the current line or the specified range and sets the current line as 
the line following the last deleted line. 


EXIT 


EX[IT] 

H/I1U.S all cUlLlIlg Sc&OaUII dllU ItJLUiIlo jfUU. l/U Ut\ X r\ 1 XVlXj V LU CUIIllIlaXlU. 

level; the edited dictionary object replaces the previous version in the data 
dictionary. 


INSERT 


I[NSERT] [range] 

Enters insert mode. You type lines to be inserted before the current line or 
before the first line of the specified range. Type CTRL/Z to exit from insert 
mode. If you do not specify a range, the current line does not change when 
you leave insert mode; if you specify a range, the Editor sets the line spe- 
cified by the range as the current line. Do not use ALL, AND, BEFORE, 
FOR REST or ^A/HOLE wVipti snprifvinf thp vancp in this pommand 


QUIT 


QUIT 

Returns you to DATATRIEVE command level and leaves the dictionary 
object unchanged by the editing session. 


REPLACE 


R[EPLACE] [range] 

Deletes the current line or the specified range and enters insert mode. 
Type CTRL/Z to exit from insert mode. The Editor sets the current line to 
the line following the last deleted line. You can use all range specifiers 
with this command. 


SUBSTITUTE 


S/str-1/[str-2][/[range]] 

Substitutes string 2 for all occurrences of string 1 in the specified range or 
in the current line if you omit the range. The Editor sets the line in which 
the last substitution occurred as the current line. If you omit string 2, the 
Editor deletes the specified string and makes no substitution. The search 
for the first occurrence of string 1 starts with the current line and proceeds 
toward the end of the text buffer except when you specify WHOLE as the 
range; when you specify WHOLE, the Editor searches and substitutes 
from the beginning to the end of the text buffer. Do not use END to specify 
the range in this command. 


TYPE 


[T[YPE]] [range] 

Displays the specified range of lines or the line following the current line 
if you omit the range. Sets the first line displayed as the current line, with 
one exception: if you specify E[ND] in the range, the Editor sets the cur- 
rent line at the end-of-buffer marker ([EOB]). 
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• To end an editing session, type EXIT, CTRL/Z, or QUIT in response to the 
QED> prompt: 

- EXIT or CTRL/Z causes DATATRIEVE to update the definition. If the object 
name is a procedure, DATATRIEVE does not invoke the procedure. 

- QUIT causes DATATRIEVE to ignore the contents of the Editor's text 
buffer, display the message "Execution failed", and return you to 
DATATRIEVE command level. 

• The DATATRIEVE Editor does not check the syntax of any DATATRIEVE 
commands or statements in the text buffer. If you make a syntax error when 
correcting your definition, DATATRIEVE responds to the error only when it 
executes the commands or statements after you exit from the Editor, or when 
you invoke the edited procedure or ready the domain. 

Usage Notes 

• The DATATRIEVE Editor has two modes: command mode (the edit mode) and 
insert mode. 

- When you use the EDIT command to invoke the Editor, the Editor prompts 
with QED>, the command mode prompt. In command mode, the Editor 
interprets all your inputs as commands, and you can display and alter the 
text of the dictionary object. 

- In insert mode, you can enter text directly into the dictionary object. To 
enter insert mode, use the INSERT and REPLACE commands. The Editor 
then prompts with IN>, the insert mode prompt. In insert mode, the Editor 
interprets all your input as new text to be entered into the dictionary object. 
To exit from insert mode, type CTRL/Z. 

• The Editor uses a line pointer to keep track of the current line. Some editing 
commands move you through the text from one line to another, thus changing 
the current line. Other commands display or alter lines at various places in the 
text but leave the current line unchanged. The line pointer keeps track of your 
position in the text. 

- The line pointer points to the entire current line, not to any part of the line. 
To display the current line, type a period (.) and carriage return in response 
to the QED> prompt. 

- The maximum line size you can edit is 132 characters. 

- The current line pointed to by the line pointer can be a blank line at the end 
of the text buffer, thus allowing you to add text to the end of the dictionary 
object. The symbol [EOB] marks the end of the text buffer. 
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• The DELETE, INSERT, REPLACE, SUBSTITUTE, and TYPE Editor com- 
mands strings all contain an optional argument that specifies the range of 
lines on which the command operates. The range may be a single line, a series 
of consecutive lines, or a group of nonsequential lines. Table 5-7 summarizes 
the range specifiers you can use with DATATRIEVE Editor commands. See 
Chapter 17 in the DATATRIEVE-1 1 User's Guide for examples of using range 
specifiers in Editor commands. 



Table 5-7: Range Specifications for Editing Commands 



Range Keyword and Format 


Range Specified 


ALL 

[%]ALL "string" 
'string' 


All lines containing the specified string. The 
search does not distinguish between upper- and 
lowercase letters. 


AND 

BE[GIN] BEGIN 
E[ND] [%]AND END [,...] 
"string" , "string" 
'string' 'string' 


All lines as specified by BEGIN, END, and 
"string". BEGIN specifies the first line of the 
dictionary object and END specifies the last 
line ([EOB]). 


BEFORE 

[%]BEF[ORE] 


All lines before the current line and the cur- 
rent line. 


BEGIN 

[%]BE[GINJ 


First line of the dictionary object. 


END 

[%]E[ND] 


Last line of the dictionary object. 


FOR 

BE[GIN] FOR 

"etrinn" n 

'string' 


Number of lines specified by n, starting with 
the the line specified by BEGIN or "string". 

-OHjVJTllN optJClllcto Lilc? 111 tot llilfcJ Ul LXlc UlCLlUildiy 

object. 


REST 

[%]R[EST 


The current line and all remaining lines in the 
dictionary object. 


string 
'string' 
"string" 


The current line or the next line containing the 
specified string. The search starts with the cur- 
rent line and continues toward the end of the 
text buffer. The Editor does not distinguish 
between upper- and lowercase letters. 


WHOLE 

[%]WH[OLE] 


All lines of the dictionary object. 


+ 

BE[GIN] 
"string" + n 
'string' 


Line that is n lines from the line specified by 
BEGIN or "string". BEGIN specifies the first 
line of the dictionary object. When you specify 
a string, the command applies to the line that 
is n lines from the next occurrence of the spe- 
cified string. 


• 

• 


The current line. 
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Note that if you want to display the rest of a dictionary object using the abbre- 
viated form of the REST specifier without a TYPE command, you must precede 
the R with a percent sign to distinguish the R from the abbreviated form of the 
REPLACE command. 

• Be careful when editing record definitions: 

- If you change the length of the record definition, you have to create a new 
data file and transfer the old information from the old file to the new one. 

- If you change the name of any fields in a record definition, you have to edit 
the procedures and reports that refer to those fields. 

• DATATRIE VE does not use any new dictionary definitions until you explicitly 
release control of the domain with the FINISH command. Thus, if you change 
the definition of a readied domain or its associated record definition, the 
changes do not have any effect until you enter a FINISH command and ready 
the domain again. 

• See the following sections for more information on DATATRIEVE Editor com- 
mands. See Chapter 17 of the DATATRIEVE -11 User's Guide for examples of 
using the DATATRIEVE Editor. 

Examples 

Edit a table, display the table with the WHOLE range specifier, search for a line 
with the TYPE command, display that line as the current line, change the line, 
and exit from the Editor. 

DTR> EDIT DEPT_TABLEdT) 
OED> WHOLE© 

CE : "Commercial Engineering"* 

PE : "Plant Engineering"* 

CS : "Customer Support"* 

RD : "Research and Development"* 

SD : "Sales Department"* 

ELSE "UNKNOWN DEPARTMENT" 

END-TABLE 
OED> TYPE "ELSE "(ret) 

ELSE "UNKNOWN DEPARTMENT" 
QED> S /UNKNOWN DEPARTMENT/UnKnown Department/® 

ELSE "Un Known Department" 
QED> EXIT© 
DTR> 
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Edit the PERSONNEL_REC record definition, display the definition with the 
WHOLE range specifier, set the START_DATE line as the current line with the 
TYPE command, and change the line with the REPLACE command. Use the 
QUIT command to exit from the Editor without changing the record definition: 

DTR> EDIT PERSONNEL_REC ADVANCED© 
QED> WHOLE© 

USING 
01 PERSON . 



05 ID 

05 EMPLOYEE-STATUS 



05 EMPLOYEE-NAME 
10 FIRST-NAME 

10 LAST-NAME 

05 DEPT 

05 START-DATE 

05 SALARY 

05 SUP_ ID 



PIC IS 3(5) , 
PIC IS X ( 1 1 ) 
QUERY-NAME IS STATUS 
QUERY-HEADER IS " STATUS " 

VALID IF STATUS EQ "TRAINEE" » " EX PER I ENCED " 
QUERY-NAME IS NAME* 

PIC IS X ( 1 ) 

QUERY-NAME IS F-NAME. 

PIC IS X ( 1 ) 

QUERY-NAME IS I NAME ♦ 

PIC IS A A A « 
USAGE IS DATE, 
PIC IS 9(5) 

ED I T-STR I NG IS $$$>$$$♦ 
PIC IS 9(5) ♦ 



QED > TYPE "DATE"© 

05 START-DATE 
QED> REPLACE© 
IN> 05 START-DATE 

IN> 

I N > - Z 

QED > WHOLE© 

USING 
01 PERSON, 
05 ID 

05 EMPLOYEE-STATUS 



05 EMPLOYEE-NAME 
10 FIRST-NAME 



10 LAST-NAME 

05 DEPT 
05 START-DATE 

05 SALARY 

05 SUP_ ID 



USAGE IS DATE, 

USAGE IS DATE© 
EDI T_STR I NG IS MMMBDDB Y ( 4 ) , © 



PIC IS 9(5) . 
PIC IS X ( 1 1 ) 
QUERY-NAME IS STATUS 
QUERY-HEADER IS "STATUS" 

VALID IF STATUS EQ " TR A I NEE " * " EXPER I ENCED " 
QUERY-NAME IS NAME, 

PIC IS X ( 1 ) 

QUERY-NAME IS F-NAME, 

PIC IS X ( 1 ) 

QUERY-NAME IS L-NAME, 
PIC IS XXX, 
USAGE IS DATE 

EDIT-STRING IS MMMBDDBY ( 4 ) , 
PIC IS 9(5) 

EDIT-STRING IS $$$,$$$, 
PIC IS 9(5) , 



QED> QUIT© 
Execution failed 
DTR> 
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5.25.1 DELETE Command 



Function 

Deletes one or more lines from the dictionary object. 
Format 



D[ELETE] [range] 



Arguments 

range 

Specifies the range of lines to be deleted. If you omit the range, 
DATATRIE VE deletes only the current line. 

Restrictions 

You can issue the DELETE command only in response to the QED> prompt. 
Results 

The Editor deletes the current line or the specified range of lines and sets the line 
pointer to the line following the last line deleted. 

Examples 

Display the TEST procedure and the current line, then delete the current line. 
Use the QUIT command to exit from the Editor without changing the procedure: 

DTR> EDIT TEST© 
QED > WHOLE© 

READY PERSONNEL READ 

FIND PERSONNEL WITH DEPT = "D98", "T32" SORTED BY STATUS , DEPT 
REPORT CURRENT 

SET REPORT_NAME = "DETAILED SALARY REPORT" 

AT TOP OF DEPT PRINT DEPT 

AT TOP OF STATUS PRINT STATUS 

PRINT ID* F I RST-NAME ! ! " " ! LAST -NAME ("NAME"), SALARY 

AT BOTTOM OF STATUS PRINT SKIP, COL 42, STATUS, SPACE, "TOTAL: 

TOTAL SALARY USING $,$$$,$$$, SKIP 
AT BOTTOM OF DEPT PRINT COL 42, DEPT, SPACE, "TOTAL:", 

TOTAL SALARY USING $,$$$,$$$, COL 42, " ", SK 

AT BOTTOM OF REPORT PRINT COL 42, "GRAND TOTAL SALARY:", 

TOTAL SALARY USING $,$$$,$$$ 
SET NO DATE 
SET COLUMNS-PAGE = 80 
END-REPORT 

oed> .© 

READY PERSONNEL READ 

QED > DELETE© 
QED > ♦ © 

FIND PERSONNEL WITH DEPT = "D98", "T32" SORTED BY STATUS, DEPT 
QED > QUIT© 
Execution failed 
DTR > 
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Delete all the AT TOP and AT BOTTOM statements in the TEST procedure. To 
do this, use two DELETE commands to delete lines that contain the string "AT" 
and lines that contain the string "TOTAL". Use the QUIT command to exit from 
the Editor without changing the procedure: 

DTR> EDIT TEST© 
OED > D ALL "AT"© 
OED > D ALL " TOTAL "(ret) 
QED > WHOLE© 

READY PERSONNEL READ 

REPORT CURRENT 

SET REPORT-NAME = "DETAILED SALARY REPORT" 

PRINT ID* F I RST-NAME ! ! " " ! LAST-NAME ("NAME")* SALARY 

SET NO DATE 

SET COLUMNS-PAGE = 80 

END-REPORT 
OED > QUIT© 
Execution failed 
DTR > 

Delete the last two SET statements in the TEST procedure. Use the QUIT com- 
mand to exit from the Editor without changing the procedure. 

DTR > EDIT TEST© 

oed> © 

FIND PERSONNEL WITH DEPT = "D98"* "T32" SORTED BY STATUS* DEPT 

qed > © 

REPORT CURRENT 

qed> © 

SET REPORT-NAME = "DETAILED SALARY REPORT" 

oed > © 

AT TOP OF DEPT PRINT DEPT 

OED> .(Ret) 

AT TOP OF DEPT PRINT DEPT 
OED> DELETE "SET" FOR 2© 
QED> WHOLE© 

READY PERSONNEL READ 

FIND PERSONNEL WITH DEPT = "D98"» "T32" SORTED BY STATUS* DEPT 
REPORT CURRENT 

SET REPORT-NAME = "DETAILED SALARY REPORT" 

AT TOP OF DEPT PRINT DEPT 

AT TOP OF STATUS PRINT STATUS 

PRINT ID* FIRST-NAME!!" " I LAST-NAME ("NAME")* SALARY 

AT BOTTOM OF STATUS PRINT SKIP* COL 42* STATUS* SPACE* "TOTAL:"* 

TOTAL SALARY USING $*$$$»$*$» SKIP 
AT BOTTOM OF DEPT PRINT COL 42* DEPT* SPACE* "TOTAL:"* 

TOTAL SALARY USING $*$$$,$$*, COL 42* " "♦ SKIP 

AT BOTTOM OF REPORT PRINT COL 42* " GRAND TOTAL SALARY:"* 

TOTAL SALARY USING $,$$$♦$$$ 
END-REPORT 

OED> iinim 
Execution failed 
DTR > 
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Establish the PRINT statement that precedes the first AT BOTTOM statement 
as the current line, then delete all lines from the beginning of the TEST proce- 
dure through the current line: 



DTR > 


EDIT 


TEST© 




QED > 


m 


READY PERSONNEL READ 




QED > 


m 


FIND PERSONNEL WITH DEPT = "D98" > " 


T32" SORTED BY STATUS 


QED> 


m 


REPORT CURRENT 




QED> 


m 


SET REPORT-NAME = "DETAILED SALARY 


REPORT" 


OED> 


m 


AT TOP OF DEPT PRINT DEPT 




OED> 


m 


AT TOP OF STATUS PRINT STATUS 




QEO> 


m 


PRINT ID* FIRST-NAME! ! " "! LAST-NAME 


< "NAME" ) * SALARY 


OED> 


.© 


PRINT ID* FIRST-NAME!!" "! LAST-NAME 


( "NAME" ) * SALARY 


OED> 


DELETE BEFORE© 




OED > 


WHOLE© 





AT BOTTOM OF STATUS PRINT SKIP* COL 42* STATUS* SPACE* "TOTAL: 

TOTAL SALARY USING $,$$$»$$$* SKIP 
AT BOTTOM OF DEPT PRINT COL 42* DEPT* SPACE* "TOTAL:"* 

TOTAL SALARY USING $,$$$*$$$, COL 42* " "> SK 

AT BOTTOM OF REPORT PRINT COL 42* "GRAND TOTAL SALARY:"* 

TOTAL SALARY USING $,$$$,$$$ 
SET NO DATE 
SET COLUMNS-PAGE = 80 
END-REPORT 
OED > QUIT© 
Execution failed 
DTR > 



5.25.2 EXIT Command 



Function 

Ends an editing session, places the edited dictionary object in the data dictionary, 
and returns you to DATATRIEVE command level. The edited dictionary object 
replaces the previous version of the object. 

Format 



| EXIT ) 
( CTRL/Z ) 



Arguments 

None 
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Restrictions 

• You must issue the EXIT or CTRL/Z command in response to the QED> 
prompt to exit from the Editor. 

• The Editor treats an EXIT command typed in response to the IN> insert mode 
prompt as a literal to be inserted in the dictionary object. 

Results 

• EXIT or CTRL/Z typed in response to the QED> Editor prompt stops an edit- 
ing session, places the edited dictionary object in the data dictionary, and 
returns you to DATATRIEVE command level. 

• CTRL/Z typed in response to the IN> insert mode prompt ends the insert 
operation and returns you to Editor command level (indicated by the QED> 
prompt). 

Usage Notes 

Changes made with the Editor affect only dictionary objects in the data diction- 
ary. They do not affect dictionary objects such as readied domains and loaded 
tables in your workspace. If, for example, you change the record definition of a 
readied domain, you cannot see the effect of this change until you finish the asso- 
ciated domain and ready it again. Similarly, to use an edited table, you must 
release the loaded version of the table and refer to it again to obtain the edited 
version. 



Examples 

Use CTRL/Z to exit from insert mode and the EXIT command to end an editing 
session: 



DTR> EDIT A© 
QED> « (RET) 

READY YACHTS 
OED> DELETE© 
OED> INSERT© 

IN> READY YACHTS READ© 

I N > • ■ Z 

OED> EXIT© 

DTR > SHOW A© 

PROCEDURE A 

READY YACHTS READ 

FIND A IN YACHTS WITH BUILDER = "GRAMPIAN" AND 

BUILDER = "AMERICAN" 
REPORT A SORTED BY BUILDER 

PRINT BUILDER* MODEL* PRICE USING $$$,$$$ 

END-REPORT 

END-PROCEDURE 

DTR > 
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5.25.3 INSERT Command 
Function 

Enters insert mode, which allows you to enter text directly into the dictionary 
object. 

Format 

l[NSERT] [range] 

Arguments 

range 

Specifies a range of lines to follow the inserted lines. If you omit the range, 
DATATRIEVE puts the inserted lines before the current line. 

Restrictions 

Do not use the following range specifiers in the INSERT command: 

• ALL 

• AND (,) 

• BEFORE 

• FOR(;) 

• REST 

• WHOLE 
Results 

• The Editor uses the IN> prompt after you enter the INSERT command to indi- 
cate that you are in insert mode. 

• The Editor inserts the lines you specify before the line specified in the range or 
before the current line if you omit a range. 

• If you do not specify a range, the current line does not change when you exit 
from insert mode. If you do specify a range, the line specified by the range 
becomes the current line. 

Usage Notes 

To exit from insert mode, type CTRL/Z. 
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Examples 

Insert comments in a procedure before the current line. Use the QUIT command 
to exit from the Editor without changing the procedure: 

DTR > EDIT A© 
OED> INSERT© 

in> \m 

IN> ! THIS IS A COMMENT© 

in> \<m 

IN> Z 
QED> WHOLE© 

! THIS IS A COMMENT 

READY YACHTS 

FIND A IN YACHTS WITH BUILDER = "GRAMPIAN" AND 

BUILDER = "AMERICAN" 
REPORT A SORTED BY BUILDER 

PRINT BUILDER t MODEL t PRICE USING $$$,$$$ 

END-REPORT 
QED> QUIT©) 
DTR > 
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Insert comments after the last line, before the first line, and before the first AT 
BOTTOM statement of the TEST procedure. Use the QUIT command to exit from 
the Editor without changing the procedure: 



n t d 
U 1 It s 


EDIT TEST© 




wt.U .•• 


INSERT BEGIN© 


T M v -- 


i® 




IN> 


! THIS 


PROCEDURE WRITES A REPORT© 


IN> 


!© 




IN> 


•■• ~y 




QED> 


INSERT END© 


IN> 


!© 




IN> 


! THIS 


IS THE END OF THE PROCEDURE 


IN> 


i© 




IN> 






QED> 


INSERT "AT 


BOTTOM "© 


IN> 


i© 




IN> 


! THIS 


SECTION FORMATS THE DETAIL 


IN> 






IN> 


■'• "7 




QED > 


WHOLE© 





THIS PROCEDURE WRITES A REPORT 
READY PERSONNEL READ 

FIND PERSONNEL WITH DEPT = "DS8", "T32" SORTED BY STATUS* DEP" 
REPORT CURRENT 

SET REPORT_N AME = "DETAILED SALARY REPORT" 
AT TOP OF DEPT PRINT DEPT 
AT TOP OF STATUS PRINT STATUS 

PRINT ID, FIRST-NAME 1 i " " ! LAST_NAME ("NAME")* SALARY 
THIS SECTION FORMATS THE DETAIL LINES OF THE REPORT 

AT BOTTOM OF STATUS PRINT SKIP, COL 42, STATUS, SPACE, "TOTAL 

TOTAL SALARY USING $,$$$,$$*, SKIP 
AT BOTTOM OF DEPT PRINT COL 42, DEPT, SPACE, "TOTAL:", 

TOTAL SALARY USING $,$$$,$$$, COL 42, " ", Si 

AT BOTTOM OF REPORT PRINT COL 42, "GRAND TOTAL SALARY:", 

TOTAL SALARY USING $,$$$,$$$ 
SET NO DATE 
SET COLUMNS-PAGE = 80 
END-REPORT 
j 

! THIS IS THE END OF THE PROCEDURE 
QED > QUIT© 
Execution failed 
DTR > 



Insert lines between the fourth and fifth lines from the current line of the TEST 
procedure. Use the QUIT command to exit from the Editor without changing the 
procedure: 

DTR> EDIT TEST© 

QED > INSERT ,+5© 
I N > ! © 

IN> ! THIS IS BEWEEN THE FOURTH AND FIFTH LINES FROM© 

IN> ! THE CURRENT LINE© 

I N > ! © 

* ^ " *" (continued on next page) 
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OED> WHOLE© 

READY PERSONNEL READ 

FIND PERSONNEL WITH DEPT = "DSB"* "T32" SORTED BY STATUS* DEPT 
REPORT CURRENT 

SET REPORT-NAME = "DETAILED SALARY REPORT" 
AT TOP OF DEPT PRINT DEPT 

! THIS IS BEWEEN THE FOURTH AND FIFTH LINES FROM 
! THE CURRENT LINE 

AT TOP OF STATUS PRINT STATUS 

PRINT ID, F I RST_NAME ! ! " "! LAST-NAME ("NAME")* SALARY 

AT BOTTOM OF STATUS PRINT SKIP* COL 42* STATUS* SPACE * "TOTAL:"* 

TOTAL SALARY USING $*$$$*$$$* SKIP 
AT BOTTOM OF DEPT PRINT COL 42* DEPT* SPACE* "TOTAL:"* 

TOTAL SALARY USING $»$$$»$$$* COL 42* " "> SKIP 

AT BOTTOM OF REPORT PRINT COL 42* "GRAND TOTAL SALARY:"* 

TOTAL SALARY USING $»$$$»$$$ 
SET NO DATE 
SET COLUMNS-PAGE = 80 
END-REPORT 
OED> QUIT© 
Execution failed 
DTR > 



5.25.4 QUIT Command 



Function 

Returns you to DATATRIE VE command level and leaves the dictionary object 
unchanged by the editing session. 

Format 



QUIT 



Arguments 

None 

Restrictions 

You cannot abbreviate the QUIT command. 
Results 

The QUIT command ends an editing session without making any changes to the 
dictionary object. 
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Examples 

Use the QUIT command to end an editing session, then show the edited object to 
confirm that no changes were made: 

DTR > EDIT A© 
QED> WHOLE© 

READY YACHTS 

PRINT FIRST 2 YACHTS 

FIND A IN YACHTS WITH BUILDER = "GRAMPIAN" AND 

BUILDER = "AMERICAN" 
REPORT A SORTED BY BUILDER 

PRINT BUILDER* MODEL t PRICE USING $$$,$*$ 
END-REPORT 



IS A COMMENT© 



THIS IS A COMMENT 
YACHTS 

FIRST 2 YACHTS 
A IN YACHTS WITH BUILDER = "GRAMPIAN" AND 
BUILDER = "AMERICAN" 
REPORT A SORTED BY BUILDER 

PRINT BUILDER* MODEL* PRICE USING $$$»*$$ 

END-REPORT 
QED> QUIT© 
Execution failed 
DTR > SHOW A (ret) 
PROCEDURE A 
READY YACHTS 
PRINT FIRST 2 YACHTS 

FIND A IN YACHTS WITH BUILDER = "GRAMPIAN" AND 

BUILDER = "AMERICAN" 
REPORT A SORTED BY BUILDER 

PRINT BUILDER t MODEL t PRICE USING $$$»*$$ 

END-REPORT 

END-PROCEDURE 

DTR> 



OED > 


INSERT BE 


IN> 


!© 


IN> 


! THI 


IN> 


!© 


IN> 


•'• "7 


OED> 


WHOLE© 




! THI 




READY 




PRINT 




FIND 



5.25.5 REPLACE Command 



Function 



Deletes the current line or a specified range of lines in a dictionary object and 
enters insert mode. 



Format 



RJEPLACE] {range] 
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Arguments 

range 

Specifies a range of lines to be deleted. If you omit the range, DATATRIEVE 
deletes the current line. 

Restrictions 

There are no range specification restrictions for the REPLACE command. 
Results 

When you enter the REPLACE command, the Editor deletes the current line or 
the lines specified by the range and then prompts with IN> to show that you are 
in insert mode. 

Usage Notes 

To exit from insert mode, type CTRL/Z. 
Examples 

Replace the current line in the TEST procedure with a comment. Use the QUIT 
command to exit from the Editor without changing the procedure: 

DTR> EDIT A (ret) 

QED> ♦ (RET) 

READY YACHTS 
0ED> REPLACE© 
IN> READY YACHTS READ© 

IN> -Z 
QED > WHOLE© 

READY YACHTS READ 

PRINT FIRST 2 YACHTS 

FIND A IN YACHTS WITH BUILDER = "GRAMPIAN" AND 

BUILDER = "AMERICAN" 
REPORT A SORTED BY BUILDER 

PRINT BUILDER t MODEL t PRICE USING $$$,$$$ 

END-REPORT 
OED> QUIT© 
Execution failed 
DTR> 



Delete all lines in a procedure and enter insert mode to create a new procedure. 
Use the QUIT command to exit from the Editor without changing the procedure: 

DTR > EDIT A© 
QED > WHOLE© 

READY YACHTS 

PRINT FIRST 2 YACHTS 

FIND A IN YACHTS WITH BUILDER = "GRAMPIAN" AND 

BUILDER = ^AMERICAN" 
REPORT A SORTED BY BUILDER 

PRINT BUILDER t MODEL > PRICE USING $$$»*$$ 
END-REPORT 

(continued on next page) 
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OED > REPLACE WHOLE© 

in> \m 

IN> ! THIS IS A TEST© 

I N > ! © 

IN> -Z 

OED > WHOLE© 

! THIS IS A TEST 

OED > QUIT© 
Execution failed 
DTR > 



Delete the first line containing the string "PRINT" and replace it with a new line. 
Use the QUIT command to exit from the Editor without changing the procedure: 

DTR > EDIT A© 

OED> REPLACE "PRINT"© 

IN> PRINT FIRST 5 YACHTS© 

I N > • • Z 

QED> WHOLE© 

READY YACHTS 

PRINT FIRST 5 YACHTS 

FIND A IN YACHTS WITH BUILDER = "GRAMPIAN" AND 

BUILDER = "AMERICAN" 
REPORT A SORTED BY BUILDER 

PRINT BUILDER t MODEL » PRICE USING $$$,$$$ 

END-REPORT 
OED> QUIT© 
Execution failed 
DTR> 



5.25.6 SUBSTITUTE Command 



Function 

Substitutes a character string for all instances of another character string in the 
current line or in the specified range of lines. 

Format 

S /string-1/[string-2][/[range]] 



Arguments 

string- 1 

Is the string of characters to be replaced. 
string-2 

Is the string of characters to replace string 1. If you omit string 2, string 1 is 
deleted from the specified line. 
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range 

Specifies the range of lines within which the substitution takes place. 



Is a delimiter. It can be any printing character not in string 1 or string 2. The 
examples in this manual use the slash (/) as the delimiter. 

Restrictions 

• The DATATRIEVE Editor recognizes only the first letter (S) of the 
SUBSTITUTE command. If you type SUBSTITUTE, the Editor displays an 
error. 

• All delimiters in a SUBSTITUTE command must be identical. The Editor 
interprets the first character after the S command as the delimiter and treats 
all characters that follow it as part of string 1 until it encounters a character 
identical to the first character. 

• If you do not specify a range, you need to specify only the first two delimiters. 

• If you specify a range, you must use all three delimiters as shown in the 
format. 

• Do not use END to specify a range for the SUBSTITUTE command. 
Results 

• The Editor searches for string 1 from the current line towards the end of the 
text buffer except when the WHOLE range is specified. When you specify 
WHOLE, the Editor begins the search at the beginning of the text buffer 
rather than at the current line. 

• If you specify a range, the Editor replaces all occurrences of string 1 in that 
range with string 2. 

• If you do not specify a range, the Editor replaces only the first occurrence of 
string 1. The first occurrence need not be in the current line. 

• The Editor displays all lines in which a substitution occurs. If no substitution 
takes place, no lines are displayed. 

• When a substitution takes place, the current line is set to the last line in which 
a substitution occurred. If no substitution takes place, the current line remains 
unchanged. 
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Examples 

Substitute the string YAHCT for the string YACHT in the current line of a pro- 
cedure. Use the QUIT command to exit from the Editor without changing the 
procedure: 

DTR > EDIT A© 

qed > .© 

READY YACHTS 
QED> S / Y A C H T / Y A H C T© 

READY YAHCTS 
QED > QUIT© 
Execution failed 
DTR > 

Substitute the string YAHCT for all occurrences of YACHT in a procedure. Use 
the QUIT command to exit from the Editor without changing the procedure: 

DTR > EDIT A (ret) 

QED> S * Y A C H T * Y A H C T * WH© 

READY YAHCTS 

PRINT FIRST 2 YAHCTS 

FIND A IN YAHCTS WITH BUILDER = "GRAMPIAN" AND 
QED > QUIT© 
Execution failed 
DTR > 

Substitute the string YAHCT for the occurrences of YACHT from the current 
line to the end of the procedure. Use the QUIT command to exit from the Editor 
without changing the procedure: 

DTR> EDIT A© 
QED> WHOLE© 

READY YACHTS 

PRINT FIRST 2 YACHTS 

FIND A IN YACHTS WITH BUILDER = "GRAMPIAN" AND 

BUILDER = "AMERICAN" 
REPORT A SORTED BY BUILDER 

PRINT BUILDER* MODEL i PRICE USING $$$>$$$ 
END-REPORT 

QED> ♦ © 

READY YACHTS 

QED > © 

PRINT FIRST 2 YACHTS 

QED > .© 

PRINT FIRST 2 YACHTS 
QED > S /YACHT/YAHCT/ REST© 

PRINT FIRST 2 YAHCTS 

FIND A IN YAHCTS WITH BUILDER = "GRAMPIAN" AND 
QED > QUIT© 
Execution failed 
DTR> 
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5.25.7 TYPE Command 

Function 

Displays the line following the current line or a specified range of lines. 
Format 



[T[YPE]] [range] 



Arguments 

range 

Specifies the range of lines to be displayed. 
Restrictions 
None 
Results 

• If you omit a range, the Editor displays the first line following the current line. 
If you specify a range, the Editor displays the range of lines. 

• The first line displayed becomes the current line, with one exception: if the 
range contains END, the line pointer points to the end-of-text buffer ([EOB]). 

Usage Notes 

• Both the command name and range are optional. Entering RETURN is the 
same as typing T and pressing RETURN. Typing WHOLE and pressing 
RETURN is the same as typing T WHOLE and pressing RETURN. 

• You can use the TYPE command to search for text strings in dictionary objects 
by enclosing the string to search for in pairs of single or double quotation 
marks. 

Examples 

Edit the TEST procedure and use the TYPE command to display the current line, 
the line following the current line, the first and last lines of the procedure, and 
the entire procedure. The TYPE command does not change text, so use the EXIT 
command to exit from the Editor: 

DTR > EDIT TEST© 
OED > T(ret) 

FIND PERSONNEL WITH DEPT = "D98", "T32" SORTED BY STATUS* DEPT 

oed> m 

REPORT CURRENT 

(continued on next page) 
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"D98" * "T32" SORTED BY STATUS * DEPT 



QED> T WH© 

READY PERSONNEL READ 
FIND PERSONNEL WITH DEPT 
REPORT CURRENT 

SET REPORT-NAME = "DETAILED SALARY REPORT" 

AT TOP OF DEPT PRINT DEPT 

AT TOP OF STATUS PRINT STATUS 

PRINT ID* F IRST-NAME ! ! " " ! LAST_NAME ("NAME")* SALARY 
AT BOTTOM OF STATUS PRINT SKIP* COL 42* STATUS* SPACE* 

TOTAL SALARY USING $*$$$*$$$* SKIP 
AT BOTTOM OF DEPT PRINT COL 42* DEPT* SPACE* "TOTAL : " * 

TOTAL SALARY USING $*$$$*$$$» COL 42* " 

AT BOTTOM OF REPORT PRINT COL 42* "GRAND TOTAL SALARY: 

TOTAL SALARY USING $*$$$*$$$ 
SET NO DATE 
SET COLUMNS-PAGE = 80 
END-REPORT 
QED> WHOLE© 

READY PERSONNEL READ 

FIND PERSONNEL WITH DEPT = "D98"* "T32" SORTED BY STATI 
REPORT CURRENT 

SET REPORT-NAME = "DETAILED SALARY REPORT" 

AT TOP OF DEPT PRINT DEPT 

AT TOP OF STATUS PRINT STATUS 

PRINT ID* FIRST-NAME!!" " ! LAST-NAME ("NAME")* SALARY 

AT BOTTOM OF STATUS PRINT SKIP* COL 42* STATUS* SPACE* 
TOTAL SALARY USING $*$$$,$$$* SKIP 

AT BOTTOM OF OEPT PRINT COL 42* DEPT* SPACE* "TOTAL:"* 
TOTAL SALARY USING $*$$$*$$$* COL 42* " 

AT BOTTOM OF REPORT PRINT COL 42* "GRAND TOTAL SALARY: 
TOTAL SALARY USING $*$*$*$$$ 

SET NO DATE 

SET COLUMNS-PAGE = 80 

END-REPORT 
OED> T BEGIN* END© 

READY PERSONNEL READ 

CEOBl 
QED> EXIT© 
DTR > 



TOTAL: " * 



SKIP 



"TOTAL 



SK I P 



Edit the TEST procedure and set the current line to the first AT BOTTOM state- 
ment. Then use the TYPE command to display all lines from the current line to 
the end of the procedure: 

DTR> EDIT TEST© 
OED> T "AT BOTTOM"© 

AT BOTTOM OF STATUS PRINT SKIP* COL 42* STATUS* SPACE* "TOTAL: " * 

OED> ,© 

AT BOTTOM OF STATUS PRINT SKIP* COL 42* STATUS* SPACE* "TOTAL:"* 
QED> T REST© 

AT BOTTOM OF STATUS PRINT SKIP* COL 42* STATUS* SPACE* "TOTAL:"* 

TOTAL SALARY USING *,$$$»$$$, SKIP 
AT BOTTOM OF DEPT PRINT COL 42* DEPT* SPACE* "TOTAL:"* 

TOTAL SALARY USING $**$$*$$$» COL 42* " " » SKIP 

AT BOTTOM OF REPORT PRINT COL 42* "GRAND TOTAL SALARY:"* 

TOTAL SALARY USING $*$$$*$$$ 
SET NO DATE 
SET COLUMNS-PAGE = 80 
END-REPORT 

QED > -z 
DTR > 
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5.26 EDIT-STRING Clause 

Function 

Specifies the output format for an elementary field value. 
Format 



EDIT_STRING [IS] edit-string 



Arguments 

edit-string 

Is one or more edit string characters that define the output format for the field 
value. 

Restrictions 

• This clause is valid only for elementary fields. 

• You must immediately precede the R edit string character with the C edit 
string character. Do not use R alone as an edit string character. 

• Do not specify one or more D edit string characters for a date field without 
specifying another valid date edit string character. DATATRIE VE interprets a 
D without another date edit string character as the DB edit string and inter- 
prets the field as numeric. 

Result 

DATATRIE VE uses the specified edit string as the default format when writing a 
field value to a file or output device. 

Usage Notes 

• If you do not include an EDIT_ STRING clause in a field definition, 
DATATRIE VE uses the PICTURE clause as the default output format. 
However, DATATRIEVE does not display a sign specified in a PICTURE 
clause unless you specify those characters in an edit string. 

• To override the default output format specified by either a PICTURE or 
EDIT_ STRING clause, specify an edit string in the PRINT statement. 

• The edit string specifies the format of a field value and can consist of one or 
more edit characters. In general, each edit character corresponds to one charac- 
ter position in the printed output. For example, 999999 specifies that the out- 
put will be six digits in six character positions. Do hot use spaces in the edit 
string. 
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• When you need several identical edit characters in an edit string, shorten the 
edit string by placing a repeat count in parentheses following the edit charac- 
ter. The edit string 9(6), for example, is the same as 999999. 

• Table 5-8 contains a list of edit string characters grouped by character type and 
function. Edit string characters function as replacement characters, insertion 
characters, or, for numeric fields, floating characters: 

— Replacement characters are place holders and are replaced by characters 
from the field's content. 

— Insertion characters are inserted in the output of the field's content. 

— Floating characters replace all but the last leading zero with spaces. The last 
leading zero is then replaced by the specified floating character. 

The characters you can use in an edit string depend on the class of the field 
(alphanumeric, numeric, or date). 



Table 5-8: Edit String Characters 



Character 
Type 


Edit String 
Character 


Description 


Alphanumeric 
Replacement 


X 
T 


Each X is replaced by one character from the field's content. 

Indicates text. The number of Ts is the length of a line. 
DATATRIEVE prints the entire field using lines of the length 
indicated. Words are not broken; if a word is longer than the 
line length specified, it is printed on a line of its own. Edit 
strings containing a T cannot contain other characters. 


Numeric 
Replacement 


9 
Z 

* (asterisk) 


Each 9 is replaced by one digit from the field's content. Nondi- 
git characters are ignored, digits are right justified in the out- 
put, and leading digit positions (if any) are filled with zeros. 

If a Z matches a leading zero in the field's content, it is replaced 
by a space. If not, Z is replaced by a digit from the field's 
content. 

If an asterisk (*) matches a leading zero in the field's content, 
an asterisk is placed in that character position. If not, it is 
replaced by a digit from the field's content. 


Alphanumeric 
Insertion 


+ (plus) 

- (hyphen) 
. (period) 
, (comma) 


If only one plus sign is specified for an alphanumeric field, it is 
inserted in that position. 

A hyphen is inserted in that character position. 

A period is inserted in that character position. 

A comma is inserted in that character position. 



(continued on next page) 
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Table 5-8: Edit String Characters (Cont.) 



Character 
Type 


Edit String 
Character 


Description 


iy Liiiici iv 

Insertion 


t VplUSJ 


XI Olliy OIlc pj.Ua nlgll lo bpcLlllcU, 11 lo IcpiclCcU. Uy a JJ1US sign 11 

the field's content is positive or a minus sign if it is negative. 




- (minus) 


If only one minus sign is specified, it is replaced by a blank if 
the field's content is positive or a minus sign if it is negative. 




. (decimal) 


A decimal point is inserted in that character position. Put only 
one decimal point in a numeric edit string. 




, (comma) 


If all the digits to the left of the comma are suppressed zeros, 
the comma is replaced by a blank. If not, a comma is inserted in 
that character position. 




CR 


If the field's content is negative, the letters CR are inserted. If 
the field's content is positive, CR is replaced by 2 blanks. Put 
only one CR in an edit string, either at the far right or the far 
left. 




DB 


If the field's content is negative, the letters DB are inserted. If 

Lilt? IltJlU. O t/UlXLCllL lo JJUolUlVCj ±JlJ lO 1 Cj^ldL/CVl Uj IWU UiallA.O. i \xv 

only one DB in an edit string, either at the far right or the far 
left. 


Alphanumeric 
and Numeric 
Insertion 


B 


A space is inserted in that character position. 




(zero) 
$ 


A zero is placed in that character position. 

If only one dollar sign is specified, it is printed in that character 
position. 




% 


A percent sign is inserted in that character position. 




/ (slash) 


A slash is inserted in that character position. 


Numeric 
Floating 
Insertion 


$ 


If more than one dollar sign is specified to the left of the other 
edit string characters, leading zeros are suppressed, and one 
dollar sign is displayed to the immediate left of the leftmost 
digit. 




+ (plus) 


If more than one plus sign is specified to the left of the other 
edit string characters, any leading zeros are suppressed, the 
sign of the field's value (plus or minus) is displayed to the 
immediate left of the leftmost character position determined by 
the other edit string characters. 




- (minus) 


If more than one minus sign is specified to the left of the other 
edit string characters, any leading zeros that the minus sign 
matches are suppressed. If the value of the field is negative, a 
minus sign is displayed to the immediate left of the leftmost 
character position determined by the other edit string 
characters. 



(continued on next page) 
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Table 5-8: Edit String Characters (Cont.) 



Character 
Type 


Edit String 
Character 


Description 


Date 

Replacement 


D 


Each D is replaced by the corresponding digit of the day of the 
month. Put no more than two Ds in a date edit string; the use of 
DD is recommended. Days of the month between 1 and 9 are 
displayed with leading zeros. 




M 


Each M is replaced by the corresponding letter of the name of 
the month. An edit string of M(9) prints the entire name of the 
month. 




N 


Each N is replaced by a digit of the number of the month. Put 
no more than two Ns in a date edit string; the use of NN is 
recommended. 




Y 


Each Y is replaced by the corresponding digit of the numeric 

vpht" Put no mnyp than font* Y<* in a Hatp prJif sifrincr* tVip imp rvf 

Jf t/C*i . JL Ul 11U iiiuiv l/llCUl -L O 111 d UulC Cult O L-L 1 1 It-. > bllv7 UuC yJL 

YY or YYYY is recommended. 




J 


Each J is replaced by the corresponding digit of the Julian date. 
Put no more that three Js in a date edit string; the use of JJJ is 
recommended. 




W 


Each W is replaced by the corresponding letter from the name 
of the day of the week. An edit string of W(9) prints the entire 
day. Put no more than 9 Ws in a date edit string. 




B 


Each B is replaced by a space in that character position. 




/ (slash) 


A slash is inserted in that character position. 




- (hyphen) 


A hyphen is inserted in that character position. 




. (period) 


A period is inserted in that character position. 



5.26.1 Formatting Alphanumeric Fields 



Usage Notes for Replacement Characters 

• The character X specifies the number of characters to be printed. Each X is 
replaced by one character from the field's content, in left-to-right order. If the 
field value has more characters than the edit string has Xs, only the leftmost 
characters are printed. If it has fewer characters than its edit string, 
DATATRIEVE pads the output with spaces on the right. 

• If an alphanumeric field contains only digits and you use the field in any arith- 
metic computations, you should define it as a numeric field. You can perform 
computations with alphanumeric fields that contain only digits; but, because 
alphanumeric fields are padded with spaces on the right, the results may not be 
valid. Edit string characters for numeric fields are explained in Section 5.27.2. 
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• The character T allows you to print alphanumeric field values on one or more 
lines. The primary use of T is to print fields containing large amounts of text. 
The number of Ts in the edit string specifies the maximum number of charac- 
ters to be printed on one line. The edit string T(20), for example, indicates that 
a line of output will contain no more than 20 characters (unless a single word 
contains more than 20 characters). Place the T edit string at the end of the 
command to avoid nonstaged output. 

• If a field contains more characters than specified in a T edit string, 
DATATRIEVE prints as many full words on the line as possible. (A word, in 
this sense, is a string of characters delimited by a space.) DATATRIEVE then 
prints the remaining characters on the next line and following lines, if neces- 
sary. DATATRIEVE does not print out trailing spaces when you use a T edit 
string. 

• When you specify a T edit string, DATATRIEVE prints only full words. It does 
not divide words. If a word is longer than the T edit string, DATATRIEVE 
prints the word in full on that line. 

Usage Notes for Insertion Characters 

• With insertion characters, you can insert a space, a zero, a dollar sign, a per- 
cent sign, a slash, a plus sign, or a hyphen in the output of a field value. 
DATATRIEVE inserts the specified characters or spaces in the positions indi- 
cated in the edit string. 

• The B (space) and slash characters are also valid for numeric edit strings, but 
cannot be used in T edit strings. 

• The hyphen is only valid in an X edit string. 
Examples 

Use a T(20) edit string to display the value of the EVALUATION field from the 
first three records in the EMP_REVIEW domain: 

DTR > SET NO PROMPT© 
DTR > READY EMP-REY IEW© 
DTR > SHOW EMP_REU_RECGD 
RECORD EMP_REV_REC 

USING 
01 EMP_REC, 

03 BADGE PIC 9(5) , 

03 NAME PIC X< 10) . 

03 JOB PIC )<( 15) ♦ 

03 EVALUATION PIC X(B0). 

03 EVAL_DATE USAGE IS DATE 

EDIT-STRING IS DD-MMM-YY. 

5 

DTR > FOR EMP_REUIEW(SD 

C0N> PRINT NAME t EVAL-DATE » EVALUATION USING T(20)t SKIPdT) 

(continued on next page) 
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EVAL 

NAME DATE EVALUATION 



BRAD H, 29-Apr-83 



Brad did a fine Job 
in implementing 
staged output* 



TERRY C* 21-Mar-83 Terry is an 

exceptional system 
manager a n d 
developer* 

DAUID D. 12-Mar-83 David is a master of 

developing report 
specifications* 



DTR> 

Print the values of the alphanumeric field ALPHA in the EDIT_TEST domain 
without an edit string and with a variety of edit strings: 

DTR> READY ED I T_TEST(ret) 
DTR> SHOW EDIT.REC© 
RECORD EDI T_REC 

USING 
01 TEST* 

03 ALPHA PIC )<( 10) * 

! 

DTR > FIND A IN ED I T_TEST(ret) 

C 2 records found] 

DTR > FOR A PRINT ALPHA© 

ALPHA 

CHALLENGER 
123 

DTR > FOR A PRINT ALPHA USING X(iO)@ 

ALPHA 

CHALLENGER 
123 

DTR > FOR A PRINT ALPHA USING X(3)i 

ALPHA 

CHA 
123 

DTR> FOR A PRINT ALPHA USING )<)</)<( 8 )m 

ALPHA 

CH/ALLENGER 
12/3 

(continued on next page) 
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DTR> FOR A PRINT ALPHA USING X ( 5 ) / X ( 5 ) (ret) 

ALPHA 

CHALL/ENGER 
123 / 

DTR > FOR A PRINT ALPHA USING X(5)-XX(r|S 

ALPHA 

CHALL-EN 
123 - 

DTR> FOR A PRINT ALPHA USING XX + XX© 

ALPHA 

CH + AL 
12 + 3 

DTR > 



5.26.2 Formatting Numeric Fields 

By using EDIT_STRING clauses in record definitions, you can format numeric 
field values in a way that is meaningful and easy to read. With edit strings you 
can suppress leading zeros and print dollar signs, percent signs, commas, decimal 
points, and plus or minus signs. For example, in the YACHT record, the 
EDIT_STRING clause for the PRICE field ($$$,$$$) causes DATATRIEVE to 
print a PRICE field value of 09870 as $9,870. 

DATATRIEVE provides three types of edit characters for numeric fields: replace- 
ment characters, insertion characters, and floating characters. 

Usage Notes for Replacement Characters 

• The 9 replacement character specifies how many digits from the field value are 
to be displayed. Each 9 in the edit string is replaced by one digit from the field 
value. DATATRIEVE ignores nondigit characters, right-justifies the output, 
and fills any leading character positions that do not contain digits with zeros. 

• The Z replacement character also specifies how many digits from the field 
value are to be displayed. Each Z in the edit string is replaced by one digit from 
the field value. Leading zeroes in the field value are replaced with spaces. 

• The asterisk replacement character specifies how many asterisks or digits from 
the field value are to be displayed. 
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• A leading zero is any zero in a field value that has only zeros to the left of it. If 
there is an implied decimal place to the left of a zero, then it is not a leading 
zero. If a Z corresponds to a leading zero in a field, a space is printed instead of a 
zero. If an asterisk corresponds to a leading zero in a field, then an asterisk is 
printed instead of a zero. 

• The following table illustrates the differences between numeric replacement 
characters. A number sign (#) represents a space: 



PICTURE 
String 


Edit 
String 


Output for Field Values 


04092 


00055 


9(5) 


None 


04092 


00055 




9(5) 


04092 


00055 




Z(5) 


#4092 


###55 




*(5) 


*4092 


***55 






0100 


0010 


99V99 


None 


0100 


0010 




99.99 


01.00 


00.10 




ZZ.ZZ 


#1.00 


##.10 




** ** 


*i.oo 


**. 10 



• Before printing a field, DATATRIEVE computes the number of digits to the 
left of the decimal point. If there is no V in the picture string, all digits are to 
the left of the decimal. If there are more digits to the left of the decimal than 
the edit string specifies with either replacement characters or floating charac- 
ters, DATATRIEVE prints an asterisk in each character position specified by 
the edit string, indicating that the edit string is not long enough for the field 
value. For example, a PICTURE clause could specify four digits for a field, and 
only two digits for an edit string: 

03 MODEL-NUMBER 

PICTURE IS 9999 
ED I T_STR I NG IS 99, 

If the field value is 1234, DATATRIEVE prints two asterisks (**) for the field 
value. Therefore, be careful to specify edit strings that are long enough for 
numeric fields. 

• If the field value has fewer digits than the edit string specifies, DATATRIEVE 
pads the output with leading zeros. You can suppress leading zeros by using 
the Z replacement character or floating characters. If there are more leading 
zeros than Zs or floating characters, the remaining zeros are displayed at the 
left of the field value, but to the right of any floating character. 
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• If you define a numeric field with the clauses PIC 9(4) and USAGE IS COMP, 
then the field can contain numbers as high as 32,768. To print the field when it 
contains a five digit number, you must use an edit string that specifies five 
digits. 



Usage Notes for Insertion Characters 

• With insertion characters, you can print the signs of fields, decimal points, dol- 
lar signs, DB or CR for negative values, percent signs, commas, zeros, slashes, 
and character string literals. 

• A PRINT statement does not display the sign of a numeric field unless you 
specify an EDIT_STRING clause in the field definition or an edit string in the 
PRINT statement: 

- To print a sign ( + or - ) in a field value (indicated by an S in the field's 
PICTURE clause), specify a + or - in the edit string for that field. The sign 
must be the first or last character in the edit string. 

- If you specify only one sign in the edit string, D ATATRIE VE prints the sign 
in the position you indicate. If you specify more than one sign in the leftmost 
part of the edit string, the sign is a floating character. 

- You can also use the edit characters DB and CR to indicate the sign of a field 
value. You can only use one DB or CR in an edit string, and it must be the 
leftmost or rightmost element of the edit string. 



The following table shows the use of the edit characters + , - , DB, and CR. A 
number sign (#) represents a space: 



PICTURE 
String 


Edit 
String 


Output for Field Values 


-1234 


+4321 


S9(4) 


None 


1234- 


4321 




-9999 


-1234 


#4321 




9999- 


1234- 


4321 




9999 + 


1234- 


4321 + 




+ 9999 


-1234 


+ 4321 




9999DB 


1234DB 


4321 




CR9999 


CR1234 


##4321 
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• For a field defined with a V in its PICTURE clause, you must use an edit string 
containing a decimal point (.) to print a value that has a decimal point in it. 
DATATRIE VE matches the decimal point in the edit string with the implied 
decimal place in the field. 

- If the edit string contains fewer digits to the right of the decimal than the 
field contains, the extra digits are not printed. 

- If the edit string contains fewer digits to the left of the decimal than the field 
contains, DATATRIEVE prints asterisks. It is best to place the period in the 
edit string in the same position as the V in the picture string. 

The following table illustrates the use of the decimal point in formatting 
numeric fields. A number sign (#) represents a space. 



PICTURE 
String 


Edit 
String 


Output for Field Values 


0321 


1234 


99V99 


None 


0321 


1234 




Z9.99 


#3.21 


12.34 




999.9 


003.2 


012.3 




9.999 


3.210 


* *** 




Z(4) 


###3 


##12 



• If the last character of the edit string is a period not followed by other input on 
the same line, DATATRIEVE treats the period as the termination of the field 
definition and not as part of the edit string. If the EDIT_ STRING clause is the 
last part of the field definition, specify two periods: the first period is part of the 
edit string and the second period ends the field definition. If the EDIT STRING 
clause is not the last part of the field definition, place the next clause on the 
same line or place a hyphen at the end of the line. 

• To print a comma, slash, percent sign, dollar sign, or zero, specify that charac- 
ter in the edit string. If there are only spaces to the left of a comma, 
DATATRIEVE prints a space instead of a comma. If you include more than one 
dollar sign, it is a floating character. The following table shows how these char- 
acters format numeric field values. A number sign (#) represents a space: 



PICTURE 
String 


Edit 
String 


Output for Field Values 


123456 


000040 


9(6) 


$999,999 


$123,456 


$000,040 






$123,456 


#####$40 




zzz,zzz 


123,456 


#####40 




999/999 


123/456 


000/040 




99% 


**% 


40% 
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Usage Notes for Floating Characters 

• You can specify three edit string characters ($, - , and + ) as floating charac- 
ters. A floating character replaces all but the last leading zero with spaces. The 
floating character ($, - , or + ) replaces the last leading zero. Floating charac- 
ters that correspond to digits are replaced by those digits. Since one character 
in the field is replaced by a floating character, specify one more character in the 
edit string than the total number of digits in the field. 

• To use a floating character, you must specify two or more of the same charac- 
ter. You can specify only one floating character in an edit string. For example, 
you cannot have both a floating minus sign and a floating dollar sign in the 
same edit string. The floating character must be the leftmost character in an 
edit string. 

• The following table shows how floating characters format field values. A num- 
ber sign (#) represents a space: 



PICTURE 
String 


Edit 
String 


Output for Field Values 


-1234 


+ 0021 


S9(4) 


+ + + +9 


-1234 


## + 21 




9 


-1234 


###21 






0015786 


0500001 


9(5)V99 


$9(5).99 


$00157.86 


$05000.01 




$$$,$$$.99 


###$157.86 


#$5,000.01 




$$$,$$$.00 


###$157.00 


#$5,000.00 



Usage Notes for Date Fields 

• A field defined as USAGE IS DATE is stored internally as a binary value. To 
print this field, DATATRIEVE must convert it to another format. If you do not 
include an EDIT_ STRING clause in the field definition for a date field, 
DATATRIEVE prints the field value in the following format: 

DD-MMM-YYYY 
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• To print the date in any other format, you must specify an EDIT_STRING 
clause in the field's definition or use an edit string in your output statement. 
By using an edit string for a date field, you can print the date in a different for- 
mat. For example, you can have DATATRIEVE print January 1, 1980 as: 

1 Jan 80 

1980/001 

Tuesday /January 01 
Jan 01 80 
1/01/80 

l-Jan-1980 Tue 

• With date edit strings you can have the date include: 

- The name of the day of the week (such as Monday, Tuesday) or just the first 
characters of the name (such as Mon, Tue) 

- The day of the month (such as 1, 2, 3) 

- The name of the month (such as January, February) or just the first charac- 
ters of the name (such as Jan, Feb) 

- The number of the month (for example, 1 for January and 12 for December) 

- The year (for example, 1980) or just the last two digits of the year (80) 

- The Julian date (for example, 001 for January 1 and 366 for December 31 in 
a leap year) 

- Delimiters to separate the parts of the date (such as a slash or period after 
the month and day) 

• In the date edit string, you specify the characters to be printed (letters, digits, 
spaces, slashes, hyphens, or periods) and the order in which the parts of the 
date are to appear (such as month, day, year). Table 5-7 shows the edit string 
characters you can use to specify the format of date values. 

• DATATRIEVE always outputs the total number of characters you specify with 
an alphabetic edit string such as M(9) or W(9). If the content of the field is 
shorter than its edit string specifies, DATATRIEVE pads the output with 
blanks. If, for example, the edit string specifies a nine-letter month with M(9) 
and the field contains a month with a name shorter than nine letters (such as 
June), DATATRIEVE prints the four-character month name and then five 
spaces. 
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• The following table illustrates the use of date edit strings for two field values: 
June 4, 1980 and November 15, 1983. A number sign (#) represents a space: 



Edit 


Output for Field Values 


Oil it iy 


June 4, 1980 


November 15, 1985 


DD-MMM-YY 


#4-Jun-80 


15-Nov-85 


MMMBDDBY(4) 


Jun##4#1980 


Nov#15#1985 


M(9)BDDBY(4) 


June#######4#1980 


November##15#1985 


NN/DD/YY 


#6/04/80 


11/15/85 


W(9) 


Wednesday 


Friday 


YYYY/JJJ 


1980/156 


1985/319 


DDBMMMBYY/WWW 


#4#Jun#80/Wed 


15#Nov#85/Fri 


DD.NN.YY 


#4.06.80 


15.11.85 
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5.27 ERASE Statement 

Function 

Permanently removes one or more data records from an indexed sequential or 
relative data file. 

Format 



ERASE [ALL [OF rsej] 



Arguments 

ALL 

Causes DATATRIE VE to permanently remove from the data file every record 
in the current collection. 

ALL OF rse 

Causes DATATRIEVE to permanently remove from the data file every record 
identified by the record selection expression. 

Restrictions 

• The domain containing the targeted record or records must be readied for 
WRITE access (see the READY Command, Section 5.44). 

• The data file containing the targeted record or records must be an indexed 
sequential file or a relative file. You cannot delete records from a sequential 
file. 

• You cannot delete a record from a view domain or a port. 

• You cannot use the ERASE statement to change or remove fields from a list in 
a hierarchical record. 

Results 

• DATATRIEVE permanently deletes the targeted record or records from the 
data file: 

- If you use the argument ALL, DATATRIEVE deletes from the data file 
every record in the current collection. 

- If you use the argument ALL OF rse, DATATRIEVE permanently deletes 
from the data file every record identified by the record selection expression. 

- If you put the keyword ERASE by itself in a FOR statement, DATATRIEVE 
permanently deletes from the data file each record specified by the FOR 
statement. 
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• If you erase a collection or record stream that contains a selected record, the 
field values of the selected record are still available in your workspace, even 
though the record has been removed from the data file by the ERASE state- 
ment. You can display the fields of that selected record, and you can use those 
field values in value expressions. The values remain in your workspace until 
you change the single record context with another SELECT statement or with 
a DROP statement, or until you release control with a RELEASE or FINISH 
command. 

• The ERASE statement permanently removes the selected record from the data 
file if you do not establish a target record stream with a FOR statement, with 
the OF rse clause, or with the keyword ALL. DATATRIEVE displays the mes- 
sage "No context for ERASE" if you have no selected record in any collection. 

Usage Note 

Before using the ERASE statement, check the current collection and selected 
record with the SHOW CURRENT command or with a PRINT statement. 

Examples 

Erase all the yachts built by Albin: 

DTR> READY YACHTS© 

DTR> FIND YACHTS WITH BUILDER EO "ALBIN "(ret) 

C 3 records found] 

DTR> ERASE ALL© 

DTR> PRINT ALL© 

DTR> 



Define a procedure to erase selected yachts: 

DTR> DEFINE PROCEDURE SELL-BOAT© 
DFN > READY YACHTS WRITE© 

DFN> FIND YACHTS WITH BUILDER EO *♦ BUILDER AND MODEL EO * ♦ MODEL© 
DFN > PRINT ALL© 

DFN > IF *."Y IF BOAT SOLD" EQ " Y " © 

DFN > THEN ERASE ALL ELSE© 

DFN > PRINT "Sell it now!"© 

DFN> END_ PROCEDURE© 

DTR> : SELL-BOAT© 

Enter BUILDER: AMERICAN© 

Enter MODEL: 26© 



LENGTH 
OUER 

MANUFACTURER MODEL RIG ALL WEIGHT BEAM PRICE 

AMERICAN 26 SLOOP 26 4 #000 08 $3 »895 

Enter Y IF BOAT SOLD: N© 
Sell it now! 



DTR> 
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5.28 EXIT Command 

Function 

Stops a DATATRIEVE session. 
Format 



( EXIT ) 
\ CTRL/Z ) 



Arguments 

None. 

Restrictions 

You must issue the EXIT or CTRL/Z command in response to the DTR> prompt 
to stop your DATATRIEVE session. 

Results 

• EXIT stops a DATATRIEVE session and returns you to system command level. 

• When you stop your DATATRIEVE session by typing either EXIT or CTRL/Z, 
DATATRIEVE automatically finishes all readied domains and releases all col- 
lections, global variables, and tables. 

• CTRL/Z does not stop your DATATRIEVE session when you are in ADT, Guide 
Mode, or the DATATRIEVE Editor. 

• CTRL/Z also does not stop your DATATRIEVE session when you enter it in 
response to an Enter prompt during the execution of a STORE or MODIFY 
statement. Entering a CTRL/Z to an Enter prompt returns you to 
DATATRIEVE command level (indicated by the DTR> prompt). 

• Entering CTRL/Z in response to the DFN>, CON>, or RW> prompts returns 
you to DATATRIEVE command level. Typing EXIT in response to these 
prompts causes a syntax error. 

Example 

End a DATATRIEVE session. 

DTR> EXIT© 
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5.29 EXTRACT Command 

Function 

Copies the dictionary definition of one or more dictionary objects from your cur- 
rent dictionary to a command file. 

Format 

EXTRACT [ON] file-spec object-name [,...] 



Arguments 

file-spec 

Is the specification of the RMS file to contain the definition or definitions in 
the following format: 

For RSTS/E systems: dev:[PPN]file-name.type 

For RSX systems: dev:[UIC]file-name.type;ver 

You must specify at least one field in the file specification. On RSTS/E sys- 
tems, you must specify a file name. DATATRIE VE uses the following defaults 
for fields not specified: 

Field Default 

dev: SY: (the system device) 

[UIC/PPN] Your default UIC/PPN 

file-name No default 

.type .CMD 

;ver 1 or next higher version 

(non-RSTS/E systems only) 

object-name 

Is the name of the dictionary object you want to extract. 
Restrictions 

• To extract the definition of a dictionary object from the dictionary, you must 
have read access privilege to the domain, record, procedure, or table. 

• An ON file-spec clause must precede the list of dictionary object names. 
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Results 

• DATATRIEVE creates a command file with the file specification you provide. 
DATATRIEVE enters into the command file a DELETE command and a 
DEFINE command for each dictionary object specified in the EXTRACT com- 
mand. The DEFINE command contains a copy of the object specified by the dic- 
tionary name. 

• The EXTRACT command copies the text of the definition exactly as it was 
entered in the dictionary by DATATRIEVE. For example, when you extract a 
domain definition, the specification for the data file is extracted just as it was 
originally entered. If only the file name (and not the device, directory, type, or 
version number) was stored in the dictionary, the EXTRACT command copies 
only the file name into the new DEFINE command. 

• When the EXTRACT command copies the definition into the command file, 
DATATRIEVE does not delete the definition from the dictionary. 

• When you invoke the command file, DELETE command in that file causes 
DATATRIEVE to delete from the dictionary the definition of any dictionary 
object with the same name as that of the extracted dictionary object. 

Usage Notes 

• The EXTRACT command enables you to create backup copies of your diction- 
ary objects and to transport data definitions to other dictionaries. 

• To invoke the command file, type @ and the command file name in response to 
the DTR> prompt. If the file type is not .CMD, you must include the file type in 
the file specification. 

• When you are moving a definition from one dictionary to another, use a SHOW 
object-name command to see if an object with the same name as that in the 
DELETE and DEFINE commands exists in the new dictionary. 

If the object exists, you must decide whether or not you want it deleted when 
you invoke the command file. If you do not want that object deleted, you must 
edit the command file to change the names in the DELETE and DEFINE 
commands. 

Be sure to anticipate the problems that might arise when you change current 
dictionaries. No two objects in the same dictionary can have the same name. If 
you shift to a new current dictionary, however, that new one may legitimately 
contain an object with the same name. 

For example, you extract the definition of procedure ABC from the dictionary 
WIDGETS.DIC. You then set your current dictionary to THINGS.DIC, which 
contains a dictionary table called ABC. If you invoke the command file, the 
DELETE ABC command in the command file deletes the table definition from 
THINGS.DIC, and the DEFINE PROCEDURE ABC command enters the pro- 
cedure definition. 
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• To invoke a command file produced by the EXTRACT command, you must 
have system read access privilege to the file and you must have DATATRIEVE 
C (control) access to any dictionary objects to be deleted from the command file. 

• The EXTRACT command does not copy the ACL of the dictionary object. After 
you invoke the command file, the ACL for the dictionary object is the default 
ACL assigned by the dictionary. Use the DEFINEP command to add other 
entries to the ACL. 

• To extract all objects in a dictionary, use the QXTR utility provided with your 
DATATRIEVE-11 installation kit. Run it at system command level by typing 
RUN $QXTR, then answer the on-line questions. The QXTR utility: 

- Provides a backup of the whole dictionary 

- Creates DEFINEP commands to reproduce the ACL of each object 

- Gives you the option of extracting an object in a form suitable for using with 
VAX-11 DATATRIEVE 

See Chapter 21 in the DATATRIEVE-11 User's Guide for information on using 
QXTR. 

Example 

Extract the definitions of the domain YACHTS and the record YACHT from the 
dictionary OLDDIC.DIC. Change the current dictionary to a new dictionary, 
NEWDIC.DIC, and use the SHOW command to check for objects with the names 
YACHTS and YACHT in NEWDIC. Then invoke the command file created with 
the EXTRACT command to copy the YACHTS and YACHT definitions to 
NEWDIC: 

DTR > EXTRACT ON MOVING YACHTS > YACHT© 
DTR> SET DICTIONARY NEWDIC© 
DTR > SHOW DICTIONARY© 

The current dictionary is SY : C 150 » 150 3 NEWDIC t DIC 

DTR > SHOW DOMAINS > RECORDS© 

Domains: 

Records: 

(continued on next page) 
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DTR> SMOVING © 
DELETE YACHTS5 

"YACHTS" has not been defined in the dictionary 
DEFINE DOMAIN YACHTS 

USING YACHT ON YACHT* DAT? 
DELETE YACHT? 

"YACHT" has not been defined in the dictionary 

DEFINE RECORD YACHT 

USING 

ALLOCATION IS LEFT-RIGHT 
01 BOAT ♦ 
03 TYPE, 

OS MANUFACTURER PIC X(10) 

QUERY-NAME IS BUILDER, 
OS MODEL PIC X( 10) . 
03 SPECIFICATIONS 

QUERY-NAME SPECS » 
OB RIG PIC X ( 6 ) 

VALID IF RIG EQ "SLOOP" » "KETCH" » "MS" t "YAWL" 
OS LENGTH_OVER_ALL PIC XXX 

UAL ID IF LOA BETWEEN 15 AND 50 

QUERY-NAME IS LOA* 
OB DISPLACEMENT PIC 99999 

QUERY-HEADER IS "WEIGHT" 

EDIT-STRING IS ZZ »ZZ9 

QUERY-NAME IS DISP. 
OB BEAM PIC 99, 
OS PRICE PIC 99999 

VALID IF PRICE>DISP*1 .3 OR PRICE EQ 

EDIT-STRING IS $$$,$$$, 

5 

[Record YACHT is -a 1 bytes lontf] 
DTR> SHOW DOMAINS, RECORDS© 
Domains: 

YACHTS 

Records: 

YACHT 

DTR > 
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5.30 FIND Statement 

Function 

Establishes a collection of records from a domain, view, collection, or list. The col- 
lection formed with the FIND statement becomes the current collection. 

Format 



FIND rse 



Arguments 

rse 

Is a record selection expression specifying the records to be included in the 
collection. 

Restrictions 

• The domain or view containing the records specified in the RSE must be read- 
ied for READ, WRITE, or MODIFY access. The source domain cannot be read- 
ied for EXTEND access. 

• The source domain cannot be a port. 

• Use the FIND statement only at DATATRIEVE command level, indicated by 
the DTR> prompt. Do not use it in a BEGIN-END block, a FOR statement, a 
REPEAT statement, or a THEN statement. 

Results 

® DATATRIEVE forms a current collection consisting of the records specified in 
the RSE. If you specify a context variable in the RSE, the collection has two 
names: CURRENT and that of the context variable. 

• When the collection has been formed, DATATRIEVE displays the message 
"[n records found]", where n is the number of records in the collection: 

- If the FIND statement is inside a procedure, DATATRIEVE does not display 
this message unless the FIND statement is the last statement in the proce- 
dure. 

— If you put the FIND statement on the same input line with other 
DATATRIEVE statements or commands, using semicolons to separate 
them, DATATRIEVE does not display this message unless the FIND state- 
ment is the last one on the line. 

• DATATRIEVE collects the records in the order it finds them in the data file. 
There is no order to the collection unless you include the SORTED BY clause in 
the record selection expression, or unless the domain uses an indexed file. 
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Usage Note 

To establish single record context in compound statements, use the RSE clauses 
of FOR, PRINT, MODIFY, WHILE, and ERASE. These RSEs can establish the 
record streams needed to control the name recognition and single record context 
inside compound statements. 

Examples 

Form a collection of yachts longer than 30 feet. Use the context variable 
BIG_ ONES to name the collection: 

DTR > READY YACHTS© 

DTR > FIND BIG_0NES IN YACHTS WITH LOA GT 30© 

L 5 7 records found] 

DTR > SHOW COLLECTIONS© 

Collections: 

BIG_0NES (also CURRENT) 

DTR > 

Form a collection of the 10 most expensive yachts sorted by descending price: 

DTR > FIND FIRST 10 YACHTS SORTED BY DESC PRICE© 

CIO records found] 

DTR > SHOW COLLECTIONS© 

Collections: 

CURRENT 

BIG_0NES 

DTR > 
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5.31 FINISH Command 

Function 

Ends your control over domains and releases any collections associated with the 
domains. 

Format 



FINISH [domain-name] [,...] 



Arguments 

domain-name 

Is the name of a readied domain you want to finish. Separate multiple domain 
names with commas (,). 

Restriction 

You can use the FINISH command only at DATATRIEVE command level, indi- 
cated by the DTR> prompt. 

Results 

• If you do not specify the names of any domains in the FINISH command, 
DATATRIEVE ends your control over all readied domains. 

• If you specify the names of one or more domains in the FINISH command, 
DATATRIEVE ends your control only over the specified domains. 

• DATATRIEVE ends your control over all collections associated with domains 
you finish. 

• The FINISH command does not remove dictionary tables from your workspace. 
You must use the RELEASE command to remove dictionary tables from your 
workspace. 

Usage Notes 

• Use the FINISH command to clear your workspace of unneeded domains and to 
end your control of access to the data file associated with a readied domain. For 
example, if you ready a domain for exclusive use, no one else can get access to 
the data file associated with that domain until you use the FINISH command 
or ready the domain again with a less restrictive access control option. 

• You need not use the FINISH command before exiting from DATATRIEVE. 
The EXIT command automatically ends your control over all readied domains, 
collections and dictionary tables. 
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• DATATRIE VE does not use any new dictionary definitions until you explicitly 
end your control over the domain with the FINISH command. Thus, if you 
change the definition of a readied domain or its associated record definition, 
the changes do not have any effect until you enter a FINISH command and 
ready the domain again. 

• If you delete the domain or record definition associated with a readied domain 
from the dictionary, you can continue to work with the domain, performing any 
operations consistent with your mode of access to the domain. You can also 
ready the domain again to change your access mode, as long as you avoid any 
conflicts of access control options. However, when you use the FINISH com- 
mand to end your control over the domain, the domain or record definition is no 
longer in the dictionary, and you can no longer get any access to the domain or 
record. 



Examples 

Use the FINISH command to end your control of the domain YACHTS: 

DTR > SHOW READY© 
Ready domains: 

YACHTS: RMS INDEXED » PROTECTED READ 



DTR> FINISH YACHTS© 
DTR > SHOW READY© 
No ready domai n s 
DTR > 



Define a domain and record, then delete and redefine them to show how new 
domain definitions do not take effect until the old domain is finished and the new 
domain is readied: 

DTR > DEFINE DOMAIN Dl USING D1REC ON D15© 
DTR> DEFINE RECORD D1REC USING© 
DFN > 01 TOP PIC ><♦© 
DFN > 5© 

[Record D1REC is 1 bytes lonsf] 

DTR > DEFINE FILE FOR Dl© 

DTR > READY Dl WRITE 5 STORE Dl© 

Enter TOP: A© 

DTR> DELETE Dl 5© 

DTR > DELETE D1REC5© 

DTR > SHOW Dl© 

"Dl" has not been defined in the dictionary 
DTR> SHOW D1REC© 

"D1REC" has not been defined in the dictionary 
DTR > SHOW READY© 
Ready d o m a i n s : 

Dl: RMS SEQUENTIAL t PROTECTED WRITE 

(continued on next page) 
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DTR> DEFINE DOMAIN Dl USING D1REC ON Dli© 
DTR > DEFINE RECORD D1REC USING© 
DFN > 01 TOP PIC XX ♦ © 
DFN> ;© 

[Record D1REC is 2 bytes Ion 3] 

DTR> STORE Dl© 

Enter TOP: BB© 

T r u n c a t i o n during assis n m e n t 

Re-enter TOP: B© 

DTR> FIND Dl© 

1 2 records found] 

DTR> PRINT ALL© 

TOP 

A 
B 

DTR > DEFINE FILE FOR Dl© 
DTR > FIND Dl© 
C 2 records found] 
DTR> PRINT ALL© 

TOP 

A 
B 

DTR > FINISH Dl© 

DTR > SHOW READY© 

No ready d o m a i n s 

DTR > READY Dl WRITE© 

DTR > FIND Dl© 

CO records f o u n d ] 

DTR> REPEAT 2 STORE Dl© 

Enter TOP: AA© 

Enter TOP: BB© 

DTR > FIND Dl© 

C 2 records found] 

DTR > PRINT ALL© 

TOP 

AA 
BB 

DTR > SHOW READY© 
Ready d o m a i n s : 

Dl: RMS SEQUENTIAL* PROTECTED WRITE 
DTR> FINISH Dl© 
DTR> SHOW READY© 
No ready d o w a i n s 
DTR> 
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5.32 FOR Statement 

Function 

Causes DATATRIEVE to execute a statement or group of statements once for 
each record in the record stream formed by a record selection expression. This 
statement provides repeating loops for DATATRIEVE operations. 

Format 

FOR rse statement 



Arguments 

rse 

Is a record selection expression that forms the record stream that controls 
1) the number of times DATATRIEVE executes the statement, and 2) the sin- 
gle record context for the statement. (See Chapter 12 of the 
DA TA TRIEVE-1 1 User's Guide for a discussion of DATATRIEVE context.) 

statement 

Is a simple or compound statement you want DATATRIEVE to execute once 
for each record in the record stream formed by the RSE. You can form com- 
pound DATATRIEVE statements with the BEGIN-END, IF-THEN-ELSE, 
and THEN statements. 

Restrictions 

• The domain containing the records specified in the RSE must be readied for 
READ, WRITE, or MODIFY access. 

• Do not include FIND, SELECT, SORT, DROP, or RELEASE statements in a 
FOR statement. 

• You cannot include a DATATRIEVE command in a FOR statement. 
Results 

• DATATRIEVE executes the statement once for each record in the record 
stream unless an ABORT statement, a CTRL/C, or a CTRL/Z typed in response 
to an Enter prompt ends the repetitions. 

• DATATRIEVE executes in the order you entered them, the statements of a 
BEGIN-END block, repeating the process for each record in the record stream. 
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• Each time DATATRIEVE executes the statement in the FOR loop, it estab- 
lishes a single record context for one record from the record stream. However, a 
statement in a BEGIN-END block in a FOR loop can create its own single 
record context. The new context lasts until DATATRIEVE completes the 
execution of the nested statement. The single record context then returns to its 
state prior to the execution of the statement. Similarly, when DATATRIEVE 
completes the execution of the FOR loop, the single record context returns to 
its state prior to the execution of the FOR loop. 

Usage Notes 

• Use the FOR statement to repeat sequences of DATATRIEVE statements. You 
do not have to know how many records the record stream contains to control 
the number of times DATATRIEVE loops through the statement. You can use 
an ABORT statement in the FOR statement to end the loop when certain con- 
ditions are met, regardless of the number of records remaining in the record 
stream. 

• Use nested FOR loops to work with lists (the repeating fields contained in hier- 
archical records). Establish the single record context in the outer loop, and the 
single list item context in the inner loop. The statement acts on all list items in 
one target record before acting on any in the next record in the record stream. 

• You can force an exit from a FOR loop in several ways: 

- Include an IF-THEN-ELSE statement in the FOR loop. Specify the exit con- 
ditions in the IF clause and include an ABORT statement in the THEN 
clause. 

- Enter a CTRL/C during the execution of a statement, or enter a CTRL/Z in 
response to an Enter prompt. Use a variable in the FOR loop as a counter to 
force an exit from the loop before all records in the record stream have been 
acted upon. To do this: 

1. Declare the variable outside the FOR loop. 

2. Inside the FOR loop, increase the value of the variable by one for each 
repetition of the loop. 

3. Specify the conditions for the exit, based on the value of the variable in 
the IF portion of the IF-THEN-ELSE statement, and include an ABORT 
statement in the THEN or ELSE clause. 

Examples 

Assign a value to the field PRICE for three yachts with prices equal to zero: 

DTR> SET NO PROMPT© 

DTR > READY YACHTS MODIFY© 

DTR > FIND FIRST 3 A IN YACHTS WITH PRICE = 0© 
C 3 records found] 
DTR> PRINT A© 

(continued on next page) 
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MANUFACTURER 



MODEL 



RIG 



LENGTH 
OVER 
ALL 



WEIGHT BEAM PRICE 



BLOCK I. 

BUCCANEER 

BUCCANEER 



40 

270 

320 



SLOOP 
SLOOP 
SLOOP 



39 
27 
32 



18 ,500 
5 ,000 
12 ,500 



12 
08 
10 



DTR > FOR A© 

CON> MODIFY USING PRICE = DISP * 1.3 + 5000© 

DTR> PRINT A (REf) 



MANUFACTURER 



MODEL 



RIG 



LENGTH 
OVER 

ALL WEIGHT BEAM 



PRICE 



BLOCK I. 

BUCCANEER 

BUCCANEER 



40 

270 

320 



SLOOP 
SLOOP 
SLOOP 



39 
27 
32 



18 ,500 
5 , 
12 ,500 



12 
08 
10 



$29 ,050 
$11 ,500 
$21 ,250 



DTR > 



Use a variable to force an end to a FOR loop before all records in the record 
stream have been acted upon: 

DTR > SET NO PROMPT© 
DTR > READY YACHTS© 
DTR> DECLARE A PIC 9.© 
DTR > A = 0© 
DTR > PRINT A© 

A 



DTR > FOR YACHTS© 

CON> BEGIN© 

CON> A = A + 1© 

CON> PRINT A , BOAT© 

CON> IF A = 5 THEN ABORT "End of 1oop"( 

CON> END© 



A MANUFACTURER 



MODEL 



LENGTH 
OVER 
RIG ALL 



WEIGHT BEAM PRICE 



1 


ALBERG 


37 MK II 


KETCH 


37 


20 ,000 


12 


$36 


,951 




ALBIN 


79 


SLOOP 


26 


a ,200 


10 


$17 


,900 


3 


ALBIN 


BALLAD 


SLOOP 


30 


7 ,276 


10 


$27 


, 5 


a 


ALBIN 


VEGA 


SLOOP 




5 ,070 


08 


$18 


,600 


5 


AMERICAN 


26 


SLOOP 


26 


4 ,000 


08 


$9 


,895 



ABORT: End of loop 

Execution terminated by "ABORT" statement 
DTR > 
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Use nested FOR loops to increase by one year the age of each child in the first two 
records of the domain FAMILIES: 



DTR> SET NO PROMPT© 

DTR > READY FAMILIES MODIFY® 

DTR> PRINT FIRST 2 FAM I L I ES© 









NUMBER 


KID 




FATHER 


MOTHER 


KIDS 


NAME 


AGE 


JIM 




ANN 




URSULA 


7 










RALPH 


3 


JIM 




LOUISE 




ANNE 


31 










JIM 


23 










ELLEN 


2G 










DAY ID 


24 










ROBERT 


1 G 


DTR > 


SET 


NO PROMPT© 








DTR > 


FOR 


FIRST 2 FAMILIES© 






CON> 




FOR KIDS© 








CON> 




MOD I F 


Y USING 


AGE = AGE 


+ K 


DTR > 


PRINT FIRST 2 FAMILIES© 












NUMBER 


KID 




FATHER 


MOTHER 


KIDS 


NAME 


AGE 


JIM 




ANN 




URSULA 


8 










RALPH 


a 


JIM 




LOUISE 


5 


ANNE 


32 










JIM 


30 










ELLEN 


27 










DAVID 


25 










ROBERT 


17 



DTR > 
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5.33 HELP Command 

Function 

Provides on-line information about the use of DATATRIEVE commands, state- 
ments, and language elements. 

Format 



HELP [ADVANCED] [topic] [,...] 



Arguments 

topic 

Is a DATATRIEVE command, statement, or statement element. Use commas 
to separate each topic from the next. 

ADVANCED 

Specifies help text for advanced DATATRIEVE language elements and 
concepts. 

Restriction 

You can use the HELP command only at DATATRIEVE command level, in 
response to the DTR> prompt. 

Results 

• DATATRIEVE displays on your terminal information for each topic you 
specify. 

• The HELP messages for each command or statement contain on-line informa- 
tion about optional arguments associated with the command or statement. 

• Once you have specified ADVANCED, it applies to all subsequent entries. For 
example, if you specify HELP ADVANCED WOMBAT, HELP; you get 
advanced help on both WOMBAT and HELP. 

• When you specify HELP with no topic, DATATRIEVE displays an explanation 
of the HELP command. If you type HELP HELP, DATATRIEVE displays a list 
of topics on which you can obtain help. If you enter HELP ADVANCED HELP, 
DATATRIEVE displays a list of advanced DATATRIEVE topics on which you 
can obtain help. 
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Examples 

Use the HELP command to obtain information on using the HELP command: 



D T R > HELP© 



Two 1 e v 


el 


5 





f 


a 


5 5 i 5 t 


an 


ce are available* b 


as 


i c 


a n d a d v a n 


c e d ♦ 


To g e t 




he 


1 


p 


f 


or t h 


e 


elementary D a t a t r i e 


v e 


s 


tateiiients ♦ 


type 


HELP fo 


1 1 


o w 


e 


d 


b 


y the 


n 


ames of the state me 


n t 


s 


for which 


help 


is r eq 


u i 


re 


d 






To ge 


t 


a list of the topic 


s 


f 


r which hel 


p is 


a v a i lab 


le 


» 


t 


y pe 

















HELP HELP 



To Set assistance with advanced D a t a t r i e v e statements* type 

HELP ADVANCED 

followed by the names of the statements for which help is 
required* To Set a list of the topics for which advanced 
help is available* type 

HELP ADVANCED HELP 



Paired square bracKe 
optional* Capital 
Words in lower case 
value is required* 
DTR> 

Use the HELP command to obtain a list of HELP topics. 

DTR> HELP HELP© 

The topics of Greatest interest to the beginning user are 
the fallowing: 



GUIDE 


READY 


FIND 


SORT 


PRINT 


MODIFY 


STORE 


EXIT 


Help is available for the 


following topics: 




ABORT 


ADT 


ASSIGNMENT 


BEGIN 


COMPUTED 


CONDITION 


DATE 


DECLARE 


DEFINE 


DEFINEP 


DELETE 


DELETEP 


DICTIONARY 


DISPLAY 


DOMAIN 


EDIT 


EDIT-STRING 


ERASE 


EXIT 


FILE 


FIND 


FINISH 


FOR 


GUIDE 


HELP 


IF 


MODIFY 


OCCURS 


PIC 


PRINT 


PROCEDURE 


RANGE 


READY 


RECORD 


RELEASE 


REPEAT 


RSE 


SELECT 


SET 


SHOW 


SHOWP 


SORT 


STORE 


SUM 


TABLE 


THEN 


USAGE 


VALUE 


VIEW 








DBMS 


OWNER 


WITHIN 




DTR > 









ts indicate that the enclosed clause is 
letters indicate D a t a t r i e v e Keywords, 
indicate that a user supplied name or 
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Use the HELP command to get general and advanced information on the FIND 
command: 



DTR> HELP FIND© 

The FIND state went is used to establish a collection of 
records from a domain* a list or a previously established 
collection* The forms of the statement are: 



FIND domain-name WITH condition 



FIND CURRENT WITH condition 



where "do m a i n - n a m e " » if used* must be the name of a readied 
domain (see HELP READY) and "condition" is a conditional 
expression . 



The FIND 


5 


tat 


from the 


d 


oma 


satisfy 


th 


e sf 


will be 


p r 


i n t 



mt establishes a collection of the records 
> the list or the current collection that 
in condition. The number of records f o u n d 
o n y our terminal. 



Examples: 



FIND YACHTS WITH LENGTH-OVER- ALL BETWEEN 2B AND 30 



FIND CURRENT WITH PRICE < 15000 

D T R > HELP ADVANCED FIND© 

The full form of the FIND statement is 



FIND rse 



where "rse" is a record selection expression. If "rse" 
contains a name for the new collection* the resulting 
collection is established under that name. 
DTR> 
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5.34 IF-THEN-ELSE Statement 

Function 

Causes DATATRIEVE to execute one of two statements or compound statements 
depending on the evaluation of a conditional (Boolean) expression. 

Format 

IF boolean-expression [THEN] statement-1 [ELSE statement-2] 



Arguments 

boolean-expression 

Is a Boolean expression (see Chapter 2). 
statement-1 

Specifies the simple or compound statement you want DATATRIEVE to 
execute when the Boolean expression evaluates to true. 

ELSE statement-2 

Specifies the simple or compound statement you want DATATRIEVE to 
execute when the Boolean expression evaluates to false. 

Restriction 

You must observe all restrictions on the individual statements used in the 
IF-THEN-ELSE statement. 

Results 

• When the Boolean expression evaluates to true, DATATRIEVE executes state- 
ment 1 in the THEN clause. The THEN keyword is optional; you can use it to 
clarify the syntax of the IF statement. 

• If you specify an ELSE clause and the Boolean expression evaluates to false, 
DATATRIEVE executes statement 2 in the ELSE clause. 

• If you do not specify an ELSE clause and the Boolean expression evaluates to 
false, DATATRIEVE does not execute statement 1 in the THEN clause and is 
ready to execute the next command or statement it encounters. 
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Usage Notes 

• You can press RETURN before any element of the IF statement except ELSE, 
and DATATRIEVE will prompt you to continue the statement. If you press 
RETURN just before typing ELSE, DATATRIEVE considers the IF statement 
complete and executes or ignores the THEN clause, depending on the evalua- 
tion of the Boolean expression. DATATRIEVE then tries to execute the ELSE 
clause as though it were a separate statement and displays an error message 
on your terminal because the ELSE clause is not a statement. When you have 
to break lines in an IF-THEN-ELSE statement, put ELSE at the end of a line 
rather than at the beginning of the next. This practice is especially important 
when you are writing a procedure, because DATATRIEVE does not check the 
syntax of the statements in the procedure until you invoke it. 

• Use an IF-THEN-ELSE statement to force an exit from a BEGIN-END block or 
from a FOR loop. Put an ABORT statement in either the THEN clause or the 
ELSE clause, and put the IF-THEN-ELSE statement in an appropriate place 
in the BEGIN-END block or FOR loop. 

• You can nest IF-THEN-ELSE statements by using an IF-THEN-ELSE state- 
ment as either statement 1 or statement 2, or both. 

Examples 

Print each yacht built by Pearson, and modify the price: 

DTR> SET NO PROMPT® 
DTR> READY YACHTS WRITE© 

CON> FOR YACHTS WITH BUILDER = " PEARSON "(ret) 



CON> BEGIN© 

CON> PRINT© 

CON> PRINT SKIP© 

CON> IF *."Y to modify price* N to skip" CONT "Y"© 

CON> THEN© 
CON> BEGIN© 

CON> MODIFY PRICE© 

CON> PRINT SKIP© 

CON> END ELSE© 

C0N> PRINT "No change"* SKIP© 

CON> IF *,"Y to continue" NOT CONT "Y" THEN© 

CON> ABORT "End of price changes"© 

CON> END© 

LENGTH 
OVER 

MANUFACTURER MODEL RIG ALL WEIGHT BEAM PRICE 

PEARSON 10M SLOOP 33 12*441 11 



Enter Y to modify price* N to skip: N© 
No change 

Enter Y to c o n t i n u e : Y© 
PEARSON 26 SLOOP 26 5*400 08 

(continued on next page) 
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Enter Y to modify price* N to skip: 



Enter PRICE: 34*521© 



Enter Y to 
PEARSON 



c o n t i n u e : 
2GW 



© 



SLOOP 



2S 



5 *200 



09 



Enter Y to modify price* N to s K i p : N© 
No change 

Enter Y to c o n t i n u e : N© 

ABORT: End of price changes 

Execution terminated by "ABORT" statement 

DTR > 

Use the IF statement to select families with fathers named Jim, and list the kids 
in those families: 

DTR > SET NO PROMPT© 

DTR> READY FAM I L I ES© 

DTR> FOR FAMILIES WITH ANY KIDS© 

C0N> IF FATHER EQ "JIM" THEN© 

C0N> PRINT "The kids of JIM and " ! MOTHER *© 

C0N> ALL K I D_NAME ("Kids with Fathers"/© 

C0N> "Named JIM") OF KIDS* SKIP© 



Kids with 
Name d 



Fat h e rs 
JIM 



The kids of JIM and ANN 



URSULA 
RALPH 



The kids of JIM and LOUISE 



ANNE 
JIM 



ELLEN 
DAVID 
ROBERT 



DTR > 
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5.35 MODIFY Statement 

Function 

Changes the value of one or more fields in a selected record or in any or all 
records in a collection or record stream. 

Format 

MODIFY [ALL] I" field-name [,...] 1 
L USING statement-1 J 

[VERIFY [USING] statement-2] 

[OF rse] 



Arguments 

ALL 

Specifies that you want to modify either all records in the CURRENT collec- 
tion or all records in the record stream specified by the OF rse clause. 

field-name 

Specifies the name of a field to modify in the target record or records. If you 
specify more than one field name, use a comma to separate field names. 
DATATRIE VE prompts you to supply a value for each specified field. 

USING statement-1 

Specifies a simple or compound statement that assigns a value or values to 
one or more fields in the target record you want to modify. This clause can 
also contain other DATATRIE VE statements, including PRINT, STORE, and 
MODIFY statements. 

VERIFY [USING] statement-2 

Specifies a statement that DATATRIEVE executes before modifying the tar- 
get record. 

OF rse 

Is a record selection expression that forms a record stream containing the 
records you want to modify. 

Restrictions 

• The domain containing the records you want to modify must be readied for 
modify or write access. 

• You cannot modify a primary or alternate key that has the NO CHANGE attri- 
bute in an RMS indexed sequential file. 
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You cannot modify a COMPUTED BY field or a REDEFINES field. 

When entering a complex MODIFY statement, use the hyphen continuation 
character if you want to press RETURN before typing the key words USING, 
VERIFY, or OF rse. If you must break an input line near one of these key 
words, you can also type the keyword at the end of a line and press RETURN. 

You cannot use a prompting value expression in a USING clause to assign a 
value to a group field. 

You must establish a context to specify the records on which the MODIFY 
statement acts. You can establish context in four ways: 

- Form a collection with a FIND statement and use a SELECT statement to 
identify a selected record (see Table 5-9). 

- Form a CURRENT collection with a FIND statement and specify ALL in the 
absence of an OF rse clause in the MODIFY statement (see Table 5-10). 

- Form a record stream with the OF rse clause in the MODIFY statement (see 
Table 5-11). 

- Use a FOR loop and form a record stream with the RSE in the FOR state- 
ment (see Table 5-12). 

Do not use ALL in the absence of the OF rse clause in a MODIFY statement 
that is part of a FOR loop. The result is a series of redundant changes to the 
records; all the records in the CURRENT collection get modified each time 
through the FOR loop. 

Avoid redundant loops when using the OF rse clause in MODIFY statements 
used in FOR loops. The OF rse clause should contain a Boolean expression 
that matches each record to be modified with one record from the record 
stream providing the data (see Example 3). 

If you specify one or more field names in a MODIFY statement, they must be 
the names of group or elementary fields that DATATRIEVE can recognize in 
the context established for the MODIFY statement. If you specify more than 
one field name, use a comma to separate field names. 

If you specify a record stream with an OF rse clause and omit the field list or 
the USING clause, you must include the keyword ALL: MODIFY ALL OF 
rse. This restriction helps remind you that this statement makes all the 
records in the record stream identical. 

If you enter CTRL/Z while being prompted for a field value, DATATRIEVE 
will end the modify operation. The field that was being modified when you 
typed CTRL/Z will contain the modified value, but the data file will not be 
modified. You must reestablish the collection to restore the original value of 
the field you were modifying. 
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Results 

• When DATATRIE VE executes a MODIFY statement, it immediately changes 
the information in the data file. See the first Usage Note. 

• DATATRIEVE prompts you for field values with this message: 
Enter field-name: 

You can enter any of the following responses: 

- To leave the value unchanged, press TAB and then press RETURN. 

- To change the value of the field, type a new value, then press RETURN. The 
new value should conform to the data description of the field, as defined in 
the record definition. 

- To change the value of an alphanumeric field to spaces, type a space and 
press RETURN. 

- To change the value of a numeric field to zero, type a zero (0) or space and 
press RETURN. To end the prompting cycle, press CTRL/Z. DATATRIEVE 
discards the changes made to the record being modified when you entered 
CTRL/Z. That record is unchanged, but if you have already modified records 
from the collection or record stream, those changes remain in effect. Each of 
those records was changed in the data file as soon as you entered your 
response to the last prompt for that record. 

• If you press RETURN in response to a prompt for a field value, DATATRIEVE 

reprompts for the value. 

• If you enter a value in response to a prompt that is longer than the length of 

the field to which it is being assigned, DATATRIEVE displays an error mes- 
sage and reprompts for the value. 

• If you omit both a list of field names and a USING clause, DATATRIEVE 

prompts for each elementary field in the record. 

• If you include a list of field names, DATATRIEVE prompts for each elementary 

field specified or implied by the list. If you include a group field name in the 
list, DATATRIEVE prompts for each elementary field contained in the 
group field. 

• If you specify a USING clause, DATATRIEVE uses any assignment state- 

ments in statement 1 to modify the values of the specified fields. 
DATATRIEVE does not then prompt for any field values unless the USING 
clause contains an assignment statement with a prompting value expression 
(value-expression = *. prompt-name). See Tables 5-9 through 5-12 for syntax 
examples of the USING clause. 
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• If you do not specify ALL or OF rse and do not put the statement in a FOR loop, 
DATATRIEVE modifies only the selected record: 

- DATATRIEVE prompts for values for each specified or implied field in the 
selected record unless you specify a USING clause that contains no prompt- 
ing value expressions. 

- If you specify a USING clause that prompts for a value that is used in an 
arithmetic calculation 

(USING PRICE = PRICE * .EXCHANGE _RATE), DATATRIEVE uses 
your response to the prompt to calculate the value of the arithmetic expres- 
sion. The value of that arithmetic expression is then the value stored in the 
updated field. 

- The context in which the MODIFY statement executes is determined by the 
selected record of the most recently established collection. If no selected 
record exists for the CURRENT collection, then the context is determined by 
the most recently established collection that has a selected record. If there is 
no selected record for any existing collection, DATATRIEVE displays an 
error message. 

Table 5-9 lists the syntax, prompts, and results of the MODIFY statements that 
change selected records. 



Table 5-9: Modifying the Selected Record 



Syntax 


Result 


MODIFY 


Prompts once for each elementary field in the record definition. 

Changes each elementary field in the selected record to the value you supply to 
the corresponding prompt. 


MODIFY fieJd-list 


Prompts once for each elementary field specified or implied by the list. 

Changes each elementary field specified or implied by the list to the value you 
supply to the corresponding prompt. 


MODIFY USING statement-1 

No prompts unless statement 1 contains prompting value expressions. 




Changes each specified or implied elementary field in the selected record to the 
values supplied by the assignment statements in statement 1. 
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• If you specify the argument ALL but do not include an OF rse clause in a 
MODIFY statement, DATATRIEVE changes all the records in the CURRENT 
collection: 

- DATATRIEVE assigns the same value to each specified and implied field of 
every record in the CURRENT collection except when the MODIFY state- 
ment includes a USING clause that assigns a value to the field with an 
arithmetic calculation that uses the old value of the field. In this case, 
DATATRIEVE uses the value of each calculation to modify the field value in 
the corresponding record (see the fourth Usage Note). 

- If the USING clause contains a prompting value expression, DATATRIEVE 
prompts only once for a value for each specified or implied field. If the 
USING clause contains no prompting value expressions, DATATRIEVE 
does not prompt for the field values. 

Table 5-10 lists the syntax, prompts, and results of MODIFY statements that 
change all the records in the CURRENT collection. 



Table 5-10: Modifying All Records in the CURRENT Collection 



Syntax 


Result 


MODIFY ALL 


Prompts once for each field in the record definition. 

Changes each field of every record in the CURRENT collection to the value you 
supply to the corresponding prompt. 


MODIFY ALL f ield-list 

Prompts once for each elementary field specified or implied by the list. 




Changes each specified or implied field of every record in the CURRENT collec- 
tion to the value you supply to the corresponding prompt. 


MODIFY ALL USING statement-1 

No prompts unless statement 1 contains prompting value expressions. 




Changes each specified or implied elementary field of every record in the CUR- 
RENT collection to the value supplied by the assignment statements in state- 
ment 1. 



• If you include an OF rse clause in a MODIFY statement, DATATRIEVE 
changes all the records in the record stream specified by the RSE as follows: 

- DATATRIEVE assigns the same value to each specified and implied field of 
every record in the record stream, except when the MODIFY statement 
includes a USING clause that assigns a value to the field with an arithmetic 
calculation that uses the old value of the field. In this case, DATATRIEVE 
uses the value of each calculation to modify the field value in the correspond- 
ing record (see Usage Note 4). 
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- If the USING clause contains a prompting value expression, DATATRIEVE 
prompts only once for a value for each specified or implied field. If the 
USING clause contains no prompting value expressions, DATATRIEVE 
does not prompt for the field values. 

- The ALL keyword is optional when you specify an OF rse clause in the 
MODIFY statement and has no effect on the result of the modify operation. 

Table 5-11 lists the syntax, prompts, and results of MODIFY statements that 
change all the records in a target record stream. 

Table 5-1 1 : Modifying All Records in a Record Stream 



Syntax Result 



MODIFY ALL OF rse 

Prompts once for each field in the record definition. 

Use with care. Changes each field of every record in the record stream to the 
value you supply to the corresponding prompt. MODIFY ALL of domain-name 
changes all the records in the domain. 

MODIFY [ALL] field-list OF rse 

Prompts once for each elementary field specified or implied by the list. 

Changes each specified or implied field of every record in the record stream to the 
value you supply to the corresponding prompt. 

MODIFY [ALL] USING statement-1 OF rse 

No prompts unless statement 1 contains prompting value expressions. 

Changes each specified or implied elementary field of every record in the record 
stream to the value supplied by the assignment statement in statement 1. 



• When you want DATATRIEVE to prompt for field values for each record in a 
record stream, include the MODIFY statement in a FOR statement. When you 
include a MODIFY statement in a FOR loop, DATATRIEVE modifies the 
records specified by the RSE in the FOR statement and prompts for field values 
as indicated in Table 5-12. 

• When you include a VERIFY clause in a MODIFY statement, DATATRIEVE 
executes statement 2 for each target record before changing that record. If 
statement 2 contains an ABORT statement and a target record causes the 
abort conditions to be true, DATATRIEVE aborts the MODIFY statement 
without changing that record and returns you to command level, indicated by 
the DTR> prompt. Any previous records changed by that MODIFY statement 
remain changed. 
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Table 5-12: Modifying Each Record in a Record Stream 



Syntax 


Result 


FOR rse MODIFY 






Prompts once for every elementary field in the record definition for each record in 




the record stream. 




Changes each field of each record to the value you supply to the corresponding 




prompt. 


FORrse MODIFY 


field-list 




Prompts once for every elementary field specified or implied by the list for each 




record in the record stream. 




Changes each specified or implied field of each record to the value you supply to 




the corresponding prompt. 


FOR rse MODIFY 


USING statement-1 




No prompts unless statement 1 contains prompting value expressions: 




• A *.prompt value expression prompts once for each record in the record stream. 




• A **. prompt value expression prompts only once, during the first execution of 




the FOR loop. 




Changes each specified or implied elementary field of each record in the record 




stream to the value supplied by the assignment statements in statement 1. 



• SET ABORT and SET NO ABORT affect a MODIFY statement with an 
ABORT statement in the VERIFY clause as follows: 

— If the MODIFY statement is not part of a procedure or command file, SET 
ABORT and SET NO ABORT do not affect the result of the ABORT. 

- If the MODIFY statement is part of a procedure or command file and SET 
ABORT is in effect, D ATATRIE VE aborts the MODIFY statement without 
changing the record that caused the abort and returns you to command level 
without executing the rest of the procedure or command file. If SET NO 
ABORT is in effect, DATATRIEVE aborts the MODIFY statement without 
changing the record that caused the abort and executes the next statement 
in the procedure or command file. 

Usage Notes 

• Use the MODIFY statement with care, as it changes information in the data 
file. DATATRIEVE catches any syntax errors you might make in entering the 
statement, but even correct syntax may contain a logical error that causes the 
wrong records to be changed or the wrong values to be entered into the fields. 

If DATATRIEVE prompts you for a field you did not expect, enter CTRL/Z to 
prevent changing records or fields you do not wish to change. It is good prac- 
tice to print each record before you modify it. 
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If you enter CTRL/Z in response to a prompt, DATATRIEVE aborts the modify 
operation. The field in the record that was being modified will contain the 
modified value, but the data file is not modified. To restore the original value of 
the field, reestablish the collection. 

Once you have modified the value or values in one or more fields, you can 
recover the previous information only by explicitly changing the new values 
back to the old ones. You may have to use several MODIFY statements to 
make the necessary changes. 

Statement 1 in the USING clause is usually an assignment statement or a 
BEGIN-END block containing more than one assignment statement. 

If you do not want all the records in the CURRENT collection or in a record 
stream created by an OF rse clause to have the same new field value, specify an 
assignment statement in the USING clause that makes the new value of a field 
in the target record depend on the old value of that field. For example: 

DTR> READY YACHTS MODIFY© 

DTR> FIND YACHTS WITH BUILDER = " PEARSON "(ret) 
CIO records found] 

DTR> MODIFY ALL USING PRICE = PRICE + 500© 
DTR> 

The specified calculation applies to each target record, but the new values 
derived for each record are independent of one another. The operation per- 
formed on a field value, however, must be appropriate to the data type of that 
field. Do not, for example, try to do arithmetic with nonnumeric data in an 
alphanumeric field. 

You can use the MODIFY statement to transfer information from one domain 
to another, from one group field to another, and from one elementary field to 
another by specifying one of the following assignment statements in the 
USING clause: 

field-name- 1 = field-name-2 

group-field-name-1 = group-field-name-2 

In both these statements, the field on the left of the assignment statement (1) 
specifies the target field and the field on the right specifies the source field (2). 
Each field name must be adequately qualified to establish the proper context 
for each side of the assignment statement. 

— Transfer of data is easiest when the field definitions are exactly the same on 
both sides of the assignment statement. If the field definitions differ, trunca- 
tions may result if the lengths of the fields do not match. 

— You must also anticipate any conflicts between data types. You can, for 
example, modify an alphanumeric field with a numeric value, but modifying 
a numeric field with a value that contains nondigit characters causes 
DATATRIEVE to display a warning message. 
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• To include other DATATRIEVE statements in the USING clause of a MODIFY 
statement, put them in a BEGIN-END block. For example, to see the target 
record before changing it, put a PRINT statement before the assignment state- 
ment in the BEGIN-END block. 

• Use a BEGIN-END block in the USING clause to create an audit trail of the 
previous values of the records you modify. Define and ready another domain 
that uses the same record definition as the one whose records you intend to 
modify. Then put an appropriate STORE statement in a BEGIN-END block in 
the USING clause of the MODIFY statement. 

• Statement 2 in the VERIFY clause typically contains an IF-THEN-ELSE 
statement and an ABORT statement to control the modification operation. 

- DATATRIEVE first checks the value you supply to a MODIFY statement 
prompt against any validation conditions specified for that field in the record 
definition. If the value passes this validation test, it is then checked against 
the conditions in the VERIFY clause of the MODIFY statement. 

- If you always use the same validation conditions for modifying and storing 
data, put those conditions in VALID IF clauses in the record definition. That 
way, DATATRIEVE reprompts you for another value for the same field if 
the value you entered does not pass the validation test. When you use an 
ABORT statement in the VERIFY clause to validate a value, you are 
returned to DATATRIEVE command level and must reenter the MODIFY 
statement when the value does not pass the validation test. 

Examples 

Increase the price of all yachts built by "AMERICAN" by 10 percent: 

DTR> READY YACHTS MODIFY© 

DTR> FIND A IN YACHTS WITH BUILDER = "AMERICAN"© 
C 2 records found] 
DTR> PRINT A (ret) 

LENGTH 



MANUFACTURER MODEL 


RIG 


OVER 

ALL 


WEIGHT 


BEAM 


PRICE 


AMERICAN 2G 
AMERICAN 2B-MS 


SLOOP 
MS 


26 
26 


4 »000 

5 >500 


08 
08 


$3 ,895 
$18 >895 


DTR> MODIFY USING PRICE 
DTR> PRINT A (ret) 


= PRICE 


* 1,1 


OF A© 






MANUFACTURER MODEL 


RIG 


LENGTH 
OVER 
ALL 


WEIGHT 


BEAM 


PRICE 


AMERICAN 26 
AMERICAN 2B-MS 


SLOOP 
MS 


26 
26 


4 »000 

5 >500 


08 
08 


$10 *884 
$20 »784 



DTR> 



5-144 Commands, Statements, and Definition Clauses 



MODIFY 

Continued 



Form a collection of yachts. Modify all the elementary fields within the group 
field SPECIFICATIONS for the records in the CURRENT collection: 



DTR > SET NO PROMPT© 

DTR> READY YACHTS MODIFY© 

DTR > FIND YACHTS WITH BEAM = 0© 

C 5 records found] 

DTR> FOR CURRENT MODIFY USING© 



C0N> BEGIN© 

C0N> PRINT SPECS© 

C0N> RIG = **,RIG© 

C0N> LOA = **,L0A© 

C0N> DISP = *. WEIGHT© 

C0N> BEAM = * 4 BEAM© 

C0N> PRICE = PRICE * 1 ♦ 1© 

C0N> END© 



LENGTH 
OVER 

RIG ALL WEIGHT BEAM PRICE 



SLOOP 32 9»500 00 

Enter RIG: (mi© 
Enter LOA: 33© 
Enter WEIGHT 12000© 
Enter BEAM: 10© 
SLOOP 32 1 1 »000 
Enter WEIGHT: ®© 



00 $29 >500 



Enter BEAM: 11© 
SLOOP 31 13»S00 
Enter WEIGHT: 15000© 
Enter BEAM: 12© 
SLOOP 35 23*200 
Enter WEIGHT: ®© 
Enter BEAM: 13© 
SLOOP 32 14,900 
Enter WEIGHT: 
Enter BEAM: 9© 
DTR > PRINT ALL© 



00 $32 »500 







00 $34,490 



LENGTH 
OYER 

MANUFACTURER MODEL RIG ALL WEIGHT BEAM PRICE 



MET ALMAST 


GALAXY 


SLOOP 


33 


1 2 »000 


10 






'DAY 


32 


SLOOP 


33 


1 1 »000 


1 1 


$32 


♦ 450 


RYDER 


S. CROSS 


SLOOP 


33 


15 ,000 


12 


$35 


»750 


TA CHIAO 


FANTASIA 


SLOOP 


33 


23 »200 


13 






WRIGHT 


SEAWIND II 


SLOOP 


33 


14 »900 


09 


$37 


♦ 928 



DTR > 
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Create a domain (UPDATES) that stores the original prices of all yachts in the 
YACHTS domain. UPDATE_REC contains four fields pertinent to the price of 
each yacht that are identical to YACHT fields: BUILDER, MODEL, 
DISPLACEMENT, and PRICE. Modify the prices of the first five yachts in the 
YACHTS domain and use MODIFY statements in nested FOR loops to change 
the prices back to their original values. 

DTR> SET NO PROMPT© 

DTR > DEFINE DOMAIN UPDATES USING UPDATE_REC ON UPDATE ♦ DAT ?© 
DTR > DEFINE RECORD UPDATE-REC USING© 
01 BOAT . 
03 TYPE, 

OS MANUFACTURER PIC X(10) 
QUERY_NAME IS BUILDER. 
OS MODEL PIC X( 10) ♦ 
03 DISPLACEMENT PIC 39999 
QUERY-HEADER IS "WEIGHT" 
ED I T-STR I NG IS ZZ #ZZ9 
QUERY-NAME IS DISP. 
03 PRICE PIC 99999 

VALID IF PRICE>DISP*1 .3 OR PRICE EQ 
EDIT-STRING IS $$$»$$$, 

5 

DTR> DEFINE FILE FOR UPDATES KEY = BUILDER <DUP)>© 
DFN > KEY = MODEL (CHANGE* DUP>© 

DTR > READY UPDATES WRITE© 
DTR > READY YACHTS WRITE© 
DTR > FOR A IN YACHTS© 

C0N> STORE UPDATES USING BOAT = A « BOAT© 

DTR > PRINT FIRST 5 UPDATES© 



MANUFACTURER 


MODEL 


WEIGHT 


PRICE 


ALBERG 


37 MK II 


20 # 000 


$36 #951 


ALBIN 


79 


4 #200 


$17 #900 


ALB I N 


BALLAD 


7 #276 


$27 #500 


ALBIN 


VEGA 


5 t070 


$18 #600 


AMERICAN 


2G 


4 * 000 


$9 #895 


DTR > FOR FIRST 5 YACHTS 


MODIFY 


PRICE© 


Enter PRICE: 


40000© 






Enter PRICE: 


20000© 






Enter PRICE: 


30000© 






Enter PRICE: 


20000© 






Enter PRICE: 


10000© 







DTR> PRINT FIRST 5 YACHTS© 



LENGTH 









OVER 












MANUFACTURER 


MODEL 


RIG 


ALL 


WEIGHT 


BEAM 


PRICE 


ALBERG 


37 MK II 


KETCH 


37 


20 


# 


12 


$40 


# 


ALBIN 


79 


SLOOP 


26 


4 


#200 


10 


$20 


#000 


ALBIN 


BALLAD 


SLOOP 


30 


7 


#276 


10 


$30 


#000 


ALBIN 


VEGA 


SLOOP 


27 


5 


#070 


08 


$20 


> 


AMERICAN 


26 


SLOOP 


26 


4 


#000 


08 


$10 


# 



(continued on next page) 
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DTR> FOR FIRST 5 A IN UPDATES© 

CON> FOR B IN YACHTS WITH BUILDER = A. BUILDER AND© 

CON> MODEL = A, MODEL© 

C0N> MODIFY USING B.PRICE = A.PRICE© 

DTR> PRINT FIRST 5 YACHTS© 

LENGTH 
OVER 



MANUFACTURER 


MODEL 


RIG 


ALL 


WEIGHT 


BEAM 


PRICE 


ALBERG 


37 MK II 


KETCH 


37 


20 


♦ 


12 


$36 


♦ 951 


ALB I N 


79 


SLOOP 


26 


a 


♦ 2 


10 


$17 


♦ 900 


ALBIN 


BALLAD 


SLOOP 


30 


1 


♦ 276 


10 


$27 


♦ 500 


ALBIN 


VEGA 


SLOOP 


27 


5 


♦ 070 


08 


$18 


♦ 600 


AMERICAN 


2B 


SLOOP 


26 


a 


♦ 


08 


$9 


♦ 895 



DTR > 
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5.36 OCCURS Clause 

The OCCURS clause defines multiple occurrences (or repetitions) of a field or 
group of fields. The multiple occurrences, called a list, create a hierarchy in the 
domain. (See Chapter 15 of the DA TA TRIEVE-1 1 User's Guide for more infor- 
mation on hierarchies.) 

The OCCURS clause has two formats: one format for a fixed number of occur- 
rences and one for a variable number of occurrences. 

5.36.1 Fixed Number of Occurrences 
Function 

Defines a fixed number of occurrences for a field or group of fields. 
Format 

OCCURS n TIMES 

Arguments 

n 

Is a positive integer specifying the number of occurrences for the field. 
Restriction 

A field definition cannot contain both an OCCURS and a COMPUTED BY 
clause. You cannot specify multiple occurrences of a COMPUTED BY field. 

Result 

This format of the OCCURS clause defines a list with a fixed number of occur- 
rences. It reserves enough space in each record to contain all the occurrences of 
the field (or fields), whether or not they contain data. 

Usage Notes 

• A record definition can contain any number of OCCURS clauses that specify a 
fixed number of occurrences. 

• A field in a group field with an OCCURS clause can contain an OCCURS 
clause. The result is a a list nested within a list (a sublist). See example 3. 
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Examples 

The following field definition reserves enough space in every record for two occur- 
rences of the elementary field KIDS_NAMES; each occurrence is 10 characters 
long. You can store up to two names (containing up to 10 characters each) in the 
KIDS_NAMES field: 

03 KIDS_NAMES PIC X( 10) 
OCCURS 2 TIMES, 

The following definition specifies that the group field KIDS_ NAMES is repeated 
twice. Each group field contains two fields: FIRST_NAME (10 characters long) 
and MIDDLE _INIT (1 character). A total of 22 characters is reserved in every 
record for the group field: 

03 K I DS_NAMES OCCURS 2 TIMES* 
05 F I RST-NAME PIC X< 10) ♦ 
05 MIDDLE. IN IT PIC X, 



The fields are stored in the record in the following order: 

K IDS-NAMES 

F I RST-NAME 

MIDDLE-INIT 
K IDS-NAMES 

FIRST-NAME 

MIDDLE-INIT 

By nesting a sublist within a list, reserve enough space in a record to store up to 
three nicknames for each KIDS_NAMES: 

03 KIDS-NAMES OCCURS 2 TIMES, 
05 FIRST-NAME PIC X(10), 
05 MIDDLE-INIT PIC X. 
05 NICKNAME PIC X ( 10 ) 
OCCURS 3 TIMES, 



The fields are stored in the following order: 

KIDS_NAMES 

FIRST-NAME 

MIDDLE-INIT 

NICKNAME 

NICKNAME 

NICKNAME 
KIDS_NAMES 

FIRST-NAME 

MIDDLE-INIT 

NICKNAME 

NICKNAME 

NICKNAME 
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5.36.2 Variable Number of Occurrences 
Function 

Defines a variable number of occurrences of a group of fields. 
Format 



OCCURS min TO max TIMES DEPENDING ON field-name 



Arguments 

min 

Is zero or a positive integer specifying the minimum number of occurrences of 
the field. DATATRIEVE does does not check this value. 

max 

Is a positive integer specifying the maximum number of occurrences of the 
field. This value must be greater than 0. 

field-name 

Is the name of a field in the same record definition. The value of the field 
determines the number of occurrences of this field. The field must be a 
numeric field containing a positive integer; it cannot be defined with digits to 
the right of the decimal point. 

Restrictions 

• No other field definition can follow the last elementary field in the group field 
containing this clause. 

• A record definition can contain only one OCCURS clause in this format. 

• A field definition cannot contain both an OCCURS and a REDEFINES clause 
or an OCCURS and a COMPUTED BY clause. 

Result 

This format of the OCCURS clause defines a list with a variable number of occur- 
rences. The number of occurrences of the group field in any record is equal to the 
value of the field specified in the OCCURS clause. Therefore, the sizes of records 
in the domain can vary. If you use the MAX argument when you define the data 
file, all records in the file have the same length. See the section in this manual on 
the DEFINE FILE command. 
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Usage Notes 

A group field containing this format of the OCCURS clause can contain one or 
more fields with an OCCURS clause. The nested OCCURS clause, however, must 
specify a fixed number of occurrences of the field. 

Example 

Define a record that specifies a variable number of occurrences. 

01 FAMILY. 

03 PARENTS . 

OB FATHER PIC X( 10) . 

OB MOTHER PIC X( 10) . 
03 NUMBER- KIDS PIC 93 ED I T_STR I NG IS Z9 . 

03 KIDS OCCURS TO 10 TIMES DEPENDING ON NUMBER_K I DS ♦ 
OB EACH_KID. 

09 K I D_NAME PIC X(10) QUERY-NAME IS KID. 
09 AGE PIC 99 EDIT-STRING IS Z9 . 

The number of occurrences of the KIDS field depends on the value of the 
NUMBER_KIDS field. If the value is 0, there are no occurrences of the field; if it 
is 1, there is one occurrence, and so on. Each occurrence of KIDS contains three 
fields: the group field EACH_KID and the elementary fields KID _ NAME and 
AGE. 
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5.37 OPEN Command 



Function 



Opens an RMS file to serve as a log of your interactive dialogue with 
DATATRIEVE. DATATRIEVE copies both your input and its own output to the 
file. 

Format 



OPEN file-spec 



Argument 

file-spec 

Is the file specification of the file to be opened. The file specification has the 
following format: 

For RSTS/E systems: dev:[PPN]file-name.type 

For RSX systems: dev:[UIC]file-name.type;ver 

You must specify at least a file-name. All other fields are optional. If you omit 
fields in the file specification, DATATRIEVE uses the following defaults: 

Field Default 

dev: SY: (the system device) 

[UIC/PPN] Your default UIC/PPN 
file-name No default 
.type .DAT 

;ver 1 or next higher version number 

(non-RSTS/E systems only) 

Restrictions 

• Do not try to create a log file of a Guide Mode session. DATATRIEVE-11 does 
not write your input to the file. 

• If you use the OPEN command in a procedure, no statements or commands in 
the procedure are written to the log file. The output of a procedure, however, is 
written to the file. 

• If you invoke a procedure after you have used the OPEN command, none of the 
commands or statements in the procedure are written to the log file. 

• You cannot have two log files open at the same time. If you enter a second 
OPEN command without closing the first log file, DATATRIEVE ignores the 
second OPEN command and the first log file remains open. 
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Results 

• Except for dialogue with the Editor, Guide Mode, ADT, and procedures, 
DATATRIE VE writes both your input and its own output to the file you specify 
in the command. 

• If you have a log file open when you invoke a command file, DATATRIEVE 
does not display the various DATATRIEVE prompts (such as DTR> and 
CON>) on the terminal or in the log file. 

• DATATRIEVE closes the file when you enter a CLOSE command, or when you 
exit from DATATRIEVE with the EXIT command or CTRL/Z. 

• If you close the file with a CLOSE or EXIT command, that command is also 
included in the file. If you close the file by exiting from DATATRIEVE with a 
CTRL/Z, neither the control character nor any of the input line is included in 
the file. 

• DATATRIEVE puts a carriage return/line feed between prompts (DTR>, 
CON>, DFN>) and your input. The file requires minor editing to make it an 
exact copy of the terminal display. 

Usage Notes 

• Keeping log files of your dialogue with DATATRIEVE can provide you with a 
transaction log and can aid in developing and debugging DATATRIEVE 
applications. 

• A log file of your dialogue with DATATRIEVE is essential when submitting a 
Software Problem Report (SPR) to DIGITAL. See DATATRIEVE -11 User's 
Guide for information on how to submit an SPR. 

• To include the contents of a procedure in a log file, enter a SHOW procedure- 
name command before invoking the procedure. 

Example 

Open a log file, display the contents of a procedure, invoke the procedure, and 
close the log file. Exit from DATATRIEVE and use the operating system TYPE 
command to display the contents of the log file: 

DTR> OPEN LOG© 

DTR> ! This is a test of the OPEN c o fruit a n d (ret) 
DTR> SHOW SELL_B0AT© 
PROCEDURE SELL_B0AT 
READY YACHTS WRITE 

FIND YACHTS WITH BUILDER EQ *, BUILDER AND MODEL EQ * ♦ MODEL 
PRINT ALL 

IF * ♦ " Y IF BOAT SOLD" EQ "Y" 

THEN ERASE ALL ELSE 

PRINT "Sell it now! " 
END-PROCEDURE 
DTR> : SELL_BOAT(ret) 
Enter BUILDER: ALB I N(ret) 
Enter MODEL: UEGA© 

(continued on next page) 
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LENGTH 
OVER 

MANUFACTURER MODEL RIG ALL WEIGHT BEAM PRICE 

ALB I N VEGA SLOOP 27 5*070 08 $18*600 

Enter Y IF BOAT SOLD: N(ret) 
Sell it now! 

DTR > EXIT© 

DTR> TYPE LOG ♦ LST(ret) 

DTR > 

! This is a test of the OPEN command 
DTR> 

READY YACHTS 
DTR> 

SHOW SELL_BOAT 

PROCEDURE SELI BOAT 

READY YACHTS WRITE 

FIND YACHTS WITH BUILDER EQ * ♦ BUILDER AND MODEL EQ *♦ MODEL 
PRINT ALL 

IF *»"Y IF BOAT SOLD" EO " Y " 

THEN ERASE ALL ELSE 

PRINT "Sell it now ! " 
END-PROCEDURE 

DTR> 

: SELL-BOAT 
Enter BUILDER: 
ALBIN 

Enter MODEL: 
MEGA 

LENGTH 
OVER 

MANUFACTURER MODEL RIG ALL WEIGHT BEAM PRICE 

ALBIN VEGA SLOOP 27 5*070 08 $18*800 

Enter Y IF BOAT SOLD : 
N 

Sell it now! 

DTR > 

EXIT 

DTR> 
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5.38 PICTURE Clause 

Function 

Specifies the storage format for field values. 
Format 



PIC[TURE] [IS] picture-string 



Arguments 

picture-string 

Is one or more picture string characters that describe the storage format for 
the field value. 

Restrictions 

• This clause is valid for elementary fields only. 

• Do not use spaces in the picture string. 
Result 

The picture string controls the storage format of the field's values. In general, 
each character in the string corresponds to one character position in the field 
value. For example, for a numeric field without a USAGE clause, 999999 spe- 
cifies six digits in six character positions, occupying six bytes of storage. 

Usage Notes 

• For numeric fields, you can also include a USAGE clause to specify the internal 
format of the digits. 

• To enter a series of identical picture string characters, place a repeat count in 
parentheses following the picture character. For example, the picture string 
9(6) is equivalent to 999999. 

• Table 5-13 contains a list of picture string characters. The picture string char- 
acters you specify for a field depend on whether the field is alphanumeric or 
numeric. 
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Table 5-13: Picture String Characters 



Field 
Class 


Picture 
Character 


Meaning 


Alphanumeric 


X 


Each X represents one character in the field. 


Numeric 


9 


Each 9 represents one digit in the field. You can specify from 1 to 
18 digits for a numeric field. 




S 


An S indicates that a sign ( + or -) is stored in the field. A picture 
string can have only one S and it must be the leftmost character. 
If there is no SIGN clause for the field, the sign shares the right- 
most character position with the lowest- valued digit, with one 
exception: the sign bit is used for the sign for COMP values. 




V 


A V indicates an implied decimal point. The decimal point does 
not occupy a character position in the field, although 
DATATRIE VE uses its location to align data in the field. A pic- 
ture string can contain only one V. 




p 


Each P specifies a decimal scaling position. Each P represents a 
"distance" in digits from an implied decimal point. (A P does not 
count toward the limit of 18 digits per field.) A P can appear at 
the right or left of the picture string. A V is unnecessary for any 
picture string containing a P. 



• The picture string for an alphanumeric field specifies the number of characters 
in the field. Only the picture string character X is valid in the picture string for 
an alphanumeric field. Each X corresponds to a single character position in the 
field. For example, the following field definition specifies that the MODEL field 
contains ten alphanumeric characters: 

OB MODEL PIC X( 10) . 

• You can use the characters 9, S, V, and P in a picture string for a numeric field 
to specify the number of digits in the field, a sign, an implied decimal point, 
and a decimal scaling factor. 

• The picture string character 9 represents one digit in the field value. For exam- 
ple, the picture string 9(4) indicates four digits, so the field value can range 
from to 9999, with one exception: if you specify both PIC 9(4) and USAGE IS 
COMP, then it is possible to store numbers as large as 32,768. You can specify 
from 1 to 18 digits for a numeric field. 
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• To specify that a numeric field can contain a sign ( + or — ), you must include 
an S in the picture string: 

— A picture string can contain only one S and it must be the leftmost character 
in the string. For example, the picture string S9(4) indicates a signed field, 
four digits in length; thus, the field value can range from -9999 to + 9999. 

— The sign specified with the S picture clause character is not printed unless 
you include an EDIT_STRING clause with the field definition. For example, 
the following field definition specifies that a sign in the picture string is to 
be printed following the last digit of the field value: 

03 CURRENT-BALANCE 

PICTURE IS S9999Y99 

ED I T_STR I NG IS $$$$9*99-, 

• The picture character V specifies the position of an "implied" decimal point: 

— The picture string 9(5)V99 specifies a seven-digit field; the last two digits of 
the field value follow the decimal point. The decimal point does not occupy a 
character position in the record; DATATRIEVE uses the implied decimal 
point in computations, Boolean expressions, and other arithmetic 
operations. 

— If there is no V in the picture string, DATATRIEVE treats the field value as 
an integer (that is, as if a V were specified to the right of the rightmost 
digit). Thus, the picture strings 999 and 999V are equal. 

— DATATRIEVE displays the implied decimal point when you retrieve the 
value from a field with a V in the picture string if you use an edit string that 
contains a decimal point (.). 

• The picture string character P specifies a decimal scaling position. Each P 
represents one decimal position between the value stored in the field and the 
implied decimal point of the value. A P does not occupy a character position in 
the field: 

— If you specify a P in a picture string, the V character is optional. For exam- 
ple, the picture strings 99PPP and 999PPV are equivalent. 

— P (or multiple Ps) must be the leftmost or rightmost character in the picture 
string. If leftmost, the decimal point is assumed to be to the left of the left- 
most P; if rightmost, the decimal point is assumed to be to the right of the 
rightmost P. 

— DATATRIEVE treats each P in a picture string as a zero. 
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5.39 PRINT Statement 

Function 

Causes DATATRIEVE to format and write values to your terminal, a file, or a 
unit record device. 

Format 



PRINT ALL ALL print-list OF rse-1 [,print-list] OF rse-2 

ON | f j le - s P ec r 
( *.prompt \ 



Arguments 

print-list 

Is a list of value expressions and formatting specifications. Table 5-14 
describes the print list elements. Table 5-15 describes the modifiers you can 
use to control the column header and format for each data field in the output 
of the PRINT statement. 

ALL 

When used alone following PRINT, ALL causes all the records in the 
CURRENT collection to be displayed on your terminal or written to the spe- 
cified file or device. 

When used with a print list, ALL causes the print list to be evaluated for each 
record in the current collection. 

When the print list begins with an inner print list, ALL is required to estab- 
lish the proper context in which to resolve references to the items in the hier- 
archical list. 

rse 

Is a record selection expression that creates the record stream DATATRIEVE 
uses to evaluate the elements of the print list. 

file-spec 

Is the file specification for the output file in the following format: 
For RSTS/E systems: dev:[PPN]file-name.type 
For RSX systems: dev.[UIC]file-name.type;ver 
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You must specify a file name. If you omit other fields in the file specification, 
DATATRIE VE uses the following defaults: 



Field 


Default 


dev: 


SY: (the system device) 


[UIC/PPN] 


Your default UIC/PPN 


file name 


No default 


•type 


.LST 


;ver 


1 or next higher version 




(non-RSTS/E systems only) 



*. prompt-name 

Is a prompting value expression that prompts you for a file specification for 
the output file. 

Restrictions 

• To print data from records in a domain, you must ready the domain for read, 
write, or modify access. You cannot print data from domains readied for extend 
access because you cannot establish collections or record streams from domains 
readied for extend access. 

• If you specify a device name in a PRINT statement, the device must be one to 
which you have access, such as a line printer, a tape drive, your own terminal, 
or another terminal. You cannot cause the output of the PRINT statement to 
be displayed on another terminal that is logged in. 

• To print character string literals, enclose the string in quotation marks. To 
include a quotation mark in a character string literal, type two quotation 
marks for every one you want in the output of the statement. For example: 

DTR> PRINT "They said* "We're sfo in . " "© 
They said* "We're sf o i n sf ♦ " 
DTR > 

Results 

• DATATRIE VE evaluates the print list and writes the resulting output to the 
specified or implied file or device. The format and content of the output depend 
on the print list elements and modifiers included in the statement. Table 5-14 
describes print list elements and Table 5-15 describes print list modifiers. 
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Table 5-14: Print List Elements 



Print List Element 


Function and Results 


f jplrLnorrip 

group-field-name [modifier] 
list-field-name 


Snppifipsi tVip fiplH wVio«sp mntpntc! arp tn Hp fnTmattpH and 
printed. The optional modifier describes the column header for 
the field, or the format of the output, or both (see Table 5-15). If 
the field is a group field, DATATRIEVE displays all the elemen- 
tary fields contained in that group field. If you omit this element, 
all the elementary fields are printed. 


literal 

*. prompt-name 

**. prompt-name [modifier] 

arithmetic-exp 

statistical-exp 


Specifies a value expression to be evaluated and printed. The 
optional modifier describes the column header for the value 
expression, or the format of the display, or both (see Table 5-15). 
Chapter 2 discusses these value expressions. 


SPACE [n] 


Inserts n horizontal spaces before the next print list element. If 
you omit n, DATATRIEVE inserts one space before the next 
print list element. 


TAB [n] 


Inserts the space of n tab characters before the next print list ele- 
ment. If you omit n, DATATRIEVE inserts the space of one tab 
before the next print list element. DATATRIEVE assumes that 
tabs are set every eight spaces and inserts enough spaces (not 
actually tab characters) in the print line to start the next print 
list element in the appropriate column. 


COLn 


Specifies that the following print list element begins in column n 
of the detail line. If n is less than the current column number, 
DATATRIEVE skips a line and begins the next print list ele- 
ment in column n. The first column in the line is column 1. 


SKIP [n] 


Begins the output of the next print list element at the beginning 
of the nth line from the current line. If n is greater than 1, the 
intervening lines are blank. If you omit n, DATATRIEVE moves, 
the cursor to the beginning of the next line. If you omit this print 
list element, DATATRIEVE displays multilined output on con- 
secutive lines. 


NEW_PAGE 


Moves the cursor to the top of a new print page. Column headers 
are suppressed, and output begins at column 1 unless another 
print list element changes the position of the cursor. 


ALL print-list OF rse 


Specifies an inner print list. DATATRIEVE evaluates the inner 
print list once for each record specified by the outer RSE. This 
print list element is generally used with a list in a hierarchical 
record to display all the values in the list for each of the records. 
DATATRIEVE uses the list name as the source of the RSE in the 
print list element. If an inner print list is the first element in a 
print list, you must add the keyword ALL before the inner print 
list (ALL ALL print-list OF rse OF rse). This additional ALL is 
not required if another print list element precedes the inner 
print list. 
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Table 5-1 5: Print List Modifiers 



Print List Modifier 


Function and Results 


("header-segment"[ / ■••]) 


Specifies one or more character string literals to be displayed as a col- 
umn header or headers above the first line of output from the PRINT 
statement. The entire modifier must be enclosed in parentheses and 
must immediately follow its associated field name or value expression. 




Suppresses the printing of column headers for all the elementary fields 
in a group field. When used with a field name or a dictionary table 
value expression, this modifier suppresses the printing of the query 
header associated with the field in its record definition or with the dic- 
tionary table in its dictionary definition. 


USING edit-string 


Imposes the characteristics of the specified edit string on the preceding 
field or value expression. The edit string must conform to the rules for 
the EDIT_STRING clause. If you follow an edit string with other print 
list items, put a space between the last character of the edit string and 
the comma that separates the edit string from the next print list item. 



• If you do not put the PRINT statement in a FOR loop and do not include a 
record selection expression or the argument ALL, DATATRIEVE uses the data 
from the selected record of the most recently formed collection with a selected 
record to evaluate the print list. DATATRIEVE evaluates the print list once 
and creates one or more lines of output, depending on the formatting options 
you specify. 

• If you specify the argument ALL and do not include an RSE, DATATRIEVE 
uses the data in the records of the CURRENT collection to evaluate the value 
expressions in the print list. DATATRIEVE evaluates the print list once for 
each record in the CURRENT collection and creates one or more lines of output 
for each record, depending on the formatting options you specify. 

• If you include a record selection expression in a PRINT statement, 
DATATRIEVE uses the data in each record in the record stream to evaluate 
the value expressions in the print list. DATATRIEVE evaluates the print list 
once for each record in the record stream and creates one or more lines of out- 
put for each record, depending on the formatting options you specify. 

• If you put a PRINT statement in a FOR loop, DATATRIEVE uses the data in 
each record in the record stream created by the rse in the FOR statement. 
DATATRIEVE evaluates the value expressions in the print list once for each 
record, and creates one or more lines of output for each record, depending on 
the formatting options you specify. 

• Unless a COL, SPACE, or TAB print list element changes the position of the 
cursor, all output begins at column 1. 
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• If you do not specify a column header or column suppression modifier after a 
field name, variable, or dictionary table value expression, DATATRIEVE uses 
the query header for the element, if one has been defined: 

- If no query header has been defined for an elementary field, the field name is 
used. If the field name has underscores in it, DATATRIEVE suppresses the 
underscores and converts the field name to a multiline header. The 
LENGTH_OVER_ ALL field in the YACHT record, for example, is con- 
verted to a three-line header: 

DTR> SET NO PROMPT© 
DTR> READY YACHTS© 

DTR> FOR FIRST 5 YACHTS PRINT BUILDER* LOA(RET) 





LENGTH 




OVER 


MANUFACTURER 


ALL 


ALBERG 


37 


ALBIN 


2S 


ALBIN 


30 


ALBIN 


27 


AMERICAN 


26 



DTR> 

- If no query header has been defined for a variable, DATATRIEVE uses the 
variable name. 

• When you specify only one header segment, the specified header is printed on 
one line above the first line of output from the PRINT statement. If the header 
is shorter than the field reserved for the value, the header is centered above the 
field. If the header is longer, the field is centered under the header. In this case, 
however, DATATRIEVE determines the placement of the other output fields 
relative to the length of the header, not the length of the field. 

• If you specify more than one header segment ("header-l"/"header-2"[/...]), the 
specified headers are printed on successive lines, centered above the associated 
field. If the edit string for the field is longer than any header segment, the 
width of the field is equivalent to the length of the edit string. If the edit string 
is shorter than any header segment, the width of the field is equivalent to the 
longest header segment. 

• If you do not include the USING edit string modifier, DATATRIEVE formats 
print list items as follows: 

- If the print list item is a field name, DATATRIEVE uses the edit string spe- 
cified for the field in the record definition or the PICTURE (PIC) clause. 

- If the print list item is a variable, DATATRIEVE uses either the edit string 
specified in the DECLARE statement that created the variable or the 
PICTURE (PIC) clause. 

- If the print list item is a prompting value expression, DATATRIEVE uses a 
default alphanumeric edit string 10 characters long, X(10). 
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• If you use a prompting value expression to specify the output file or device, 
DATATRIE VE prompts you for the name when it executes the PRINT state- 
ment. If you omit the ON clause, DATATRIEVE displays the output on your 
terminal. 

• If you are using an RSX operating system and end your file specification with 
the name of a line printer or another terminal that is not a spooled device, the 
output of a PRINT statement can be immediately displayed on the device. 
Consult RSX-11MIM-PLUS System Managers Guide, for details regarding 
spooled devices. 

Usage Notes 

• PRINT statement arguments allow you to specify the following information: 

- The data to be printed to a terminal or file. Data can be the contents of a 
field, the value of a variable, or any other value expression. 

- The format of the data. You can specify an edit string to override any edit 
string in the field or variable definition or to format a value expression. 

- The spacing (both horizontal and vertical) for the output. You can insert 
tabs or spaces between columns or skip lines between lines of output. 

- Column headers for each column of data in the output. You can also specify 
that no header is to be printed above a column. 

• When you omit the print list from a PRINT statement, DATATRIEVE uses the 
following defaults for data display and formatting: 

- The data displayed on the terminal or written to a file is the contents of all 
fields in the selected record (PRINT), the records in the CURRENT collec- 
tion (PRINT ALL), or the records in the record stream formed by the rse in 
the PRINT statement (PRINT rse). 

- The format of the field's contents is determined by the record definition. 

- The horizontal spacing is determined by the longest of three items: 1) the 
edit string, if specified, 2) the longest header segment, if specified, or 3) the 
length of the value of the print list element. Output begins in column 1 and 
is single-spaced, with a single blank line following the header line. 

- Column headers for fields are the query headers specified in the record 
definition. If no query headers were specified, DATATRIEVE uses the field 
names for headers. If the field name contains an underscore, DATATRIEVE 
suppresses the underscore, places each part of the field name on a separate 
line, and centers each part of the field name above the column of data. If the 
query header contains only a hyphen, DATATRIEVE does not print any 
header. 

• Use inner print lists to display data in the lists of hierarchical records. 
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Examples 

Write to a file the builder and length-over-all of each yacht: 

DTR > PRINT BUILDER » LOA OF YACHTS ON REPORT ♦ REP© 
DTR> 



Display on your terminal the data on five yachts that are 30 or 31 feet long: 

DTR> READY YACHTS© 

DTR > PRINT FIRST 5 YACHTS WITH LOA BETWEEN 30 AND 31© 

LENGTH 
OYER 

MANUFACTURER MODEL RIG ALL WEIGHT BEAM PRICE 



ALBIN BALLAD SLOOP 30 7*276 10 $27 *500 

BOMBAY CLIPPER SLOOP 31 9*400 11 $23*950 

C&:C CORVETTE SLOOP 31 8*650 09 

CAL 3-30 SLOOP 30 10*500 10 

FISHER 30 KETCH 30 14*500 09 



DTR> 



Use the PRINT statement to display the group field SPECS from a selected 
record: 

DTR> FIND YACHTS WITH BUILDER = " PEARSON "(ret) 

[10 records found] 

DTR > SELECT© 

DTR > PR INT SPECS© 

LENGTH 
OYER 

RIG ALL WEIGHT BEAM PRICE 
SLOOP 33 12*441 11 
DTR > 



With an inner print list, display the father and kids of the first two families: 

DTR > READY FAMILIES© 

DTR > PRINT FATHER* ALL EACH_K I D OF KIDS OF FIRST 2 FAMILIES© 
KID 



FATHER 


NAME 


AGE 


JIM 


URSULA 


7 




RALPH 


3 


JIM 


ANNE 


31 




JIM 


29 




ELLEN 


2S 




DAY ID 


2S 




ROBERT 


IB 



DTR > 
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Display the first two records of a target stream formed by a FOR loop: 

DTR> SET NO PROMPT© 
DTR> FOR FIRST 2 YACHTS© 
C0N> PRINT TYPE , LOA , PRICE© 

LENGTH 
OUER 

MANUFACTURER MODEL ALL PRICE 

ALBERG 37 MK II 37 $36,951 

ALB I N 79 2S $17,900 

DTR> 



Display the hierarchical records of a target record stream formed by nested FOR 
loops: 

DTR > SET NO PROMPT© 

DTR > FOR FIRST 2 FAMILIES© 

C0N> FOR KIDS© 

C0N> PRINT MOTHER, FATHER, KID-NAME© 

KID 

MOTHER FATHER NAME 



ANN 


JIM 


URSULA 


ANN 


JIM 


RALPH 


LOUISE 


JIM 


ANNE 


LOUISE 


JIM 


JIM 


LOUISE 


JIM 


ELLEN 


LOUISE 


JIM 


DAUID 


LOUISE 


JIM 


ROBERT 


DTR > 







Display the records from a record stream formed by a PRINT statement contain- 
ing two RSEs (inner print list precedes any other print list): 

DTR > SET NO PROMPT© 

DTR> PRINT ALL ALL K I D_NAME OF FIRST 1 KIDS,© 
CON> MOTHER OF FIRST 2 FAMILIES© 

KID 

NAME MOTHER 

URSULA ANN 
ANNE LOUISE 

DTR > 
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5.40 QUERY-HEADER Clause 

Function 

Specifies the column header DATATRIEVE uses when it formats the display of 
the field value for the PRINT statement or for the Report Writer AT and PRINT 
statements. 

Format 



QUERY-HEADER [IS] {"header-segment"} [/...] 



Arguments 

"header-segment" 

Is the column header displayed above a column of data. If you specify only one 
character string literal, that string is printed on one line above the column. If 
you specify more than one character string literal, you must separate them by 
a slash (/). DATATRIEVE prints the literals on successive lines, centered 
above the column. 

Restrictions 

• This clause is valid for elementary fields only. 

• The column header can include any character except a carriage return, line 
feed, or control character. To include a quotation mark in a column header, 
precede it with a second quotation mark. (See the third example.) 

Results 

• If you include this clause, DATATRIEVE uses the specified query header as 
the default column header when printing the field. 

• If you omit this clause, DATATRIEVE uses the field name as the default col- 
umn header when printing the field. 

Usage Note 

You can override the QUERY_HEADER clause by using the column header 
modifier for print list items in the PRINT statement and Report Writer AT and 
PRINT statements. The column header modifier overrides the default query 
header specified in the field definition (see Table 5-15 for more information on 
print list modifiers). 
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Examples 

Give the DISPLACEMENT field of YACHTS a default query header of WEIGHT: 

OB DISPLACEMENT PIC 93939 

QUERY -HEADER IS "WEIGHT" 
ED I T_STR I NG IS ZZ ,ZZ9 
QUERY-NAME IS DISP* 



Give the LENGTH_OVER_ALL field in YACHTS a column header of LENGTH 
(IN FEET), printed on two separate lines: 

OS LENGTH-OUER-ALL PIC XXX 

QUERY-HEADER IS " LENGTH "/"( I N FEET)". 



When you display the LOA field, DATATRIEVE prints the column header as: 

LENGTH 
(IN FEET) 



Give the LENGTH. OVER_ ALL field a three-line column header with one letter 
per line: 

06 LENGTH-OVER. ALL PIC XXX 

QUERY-HEADER IS "L"/"0"/"A" 



DATATRIEVE prints the column header as: 

L 

A 
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5.41 QUERY-NAME Clause 

Function 

Specifies an alternate name for the field. 
Format 

QUERY_NAME [IS] query-name 

Arguments 

query-name 

Is the query name. The rules for forming and using a query name are the 
same as those for a field name. 

Restriction 

The query name must conform to rules for naming DATATRIEVE fields. 
Result 

You can use the the query name anywhere you can use the field name. 
Usage Notes 

• This clause is valid for both group and elementary fields. 

• Use the QUERY_NAME clause when a field name is too long to use with ease. 

• Like a field name, a query name can duplicate another query name (or a field 
name) in the record. A query name can also be qualified by other query names 
or field names. 

Examples 

Define DISP as a alternate name for the DISPLACEMENT field: 

OB DISPLACEMENT PIC 99999 

QUERY-NAME IS DISP, 

Define SPECS as an alternate name for the group field SPECIFICATIONS: 

03 SPECIFICATIONS 

QUERY-NAME SPECS, 

For the field DELINQUENT. ACCOUNT_STATUS, define the query name 
SPECIAL_HANDLING. 

09 DELINQUENT_ACCOUNT_STATUS 
PIC X 

QUERY-NAME IS SPECIAL-HANDLING, 
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5.42 READY Command 

Function 

Gives you access to one or more domains and controls the access of other users to 
those domains. 



Format 



READY / domain-name 


(passwd)"! 
. (*> J 


[AS alias-1] 






"protected" 




" READ 








SHARED 




WRITE 








EXCLUSIVE 




MODIFY 












EXTEND 







Arguments 

domain-name 

Is the name of a domain you want to access, 
alias 

Is an alternative name for the domain name specified in the command. You 
can use the alias in place of the name of the domain where the syntax of a 
statement calls for a domain name. 

(passwd) 

(*) 

Is the password necessary to gain access to the domain. The parentheses are 
required. Use the asterisk to have DATATRIEVE prompt for the password. If 
you omit this argument, DATATRIEVE uses your login UIC/PPN to verify 
your access privileges. 

PROTECTED 

SHARED 

EXCLUSIVE 

Are options you can select to control the access of other users to a domain you 
ready. Access options are described in table 5-16. 
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Table 5-16: Access Options 



Option 


Access Constraints 


PROTECTED 

SHARED 
EXCLUSIVE 


Any other user can have only read access to records in the domain. No other user 
can have write, modify, or extend access to the records in the domain. This option 
is the default for domains based on RMS files. 

Any other user can have access to the domain at the same time, in protected or 
shared mode. Individual records, however, cannot be shared at the same time. 

No other user can have access to the domain at the same time, in any access 
mode. The file containing the data is locked by RMS. 



READ 
MODIFY 
WRITE 
EXTEND 

Are options you can select to request a mode of access to a domain. Privileges 
assigned to you in the domain's access control list determine the mode of 
access you can specify. Table 5-17 describes access modes and lists the privi- 
leges needed for each access mode. 



Table 5-17: Access Modes 



Mode 


Type of Access 


Privileges Needed 


READ 


You can only retrieve records (the default). 


Read, write, or modify 


MODIFY 


You can retrieve and modify records. 


Modify or write 


WRITE 


You can retrieve, modify, store, and erase 
records. 


Write 


EXTEND 


You can only store records. 


Extend, write, or modify 



Restrictions 



• You must have E (execute) access privilege to the associated record definition 
before you can ready a domain. 

• You must have privilege to the domain appropriate for the type of access spe- 
cified. Table 5-17 lists privileges needed for access modes. 

• You can ready only domains catalogued in your current dictionary. 

• You can ready only domains whose associated record definitions are catalogued 
in your current dictionary. 
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• You cannot ready a domain unless the data file specified in the domain defini- 
tion exists. When the data file exists: 

- You must have at least operating system read access to the file before you 
can ready the domain for read access. 

— You must have operating system write access to the file before you can ready 
the domain for write, modify, or extend access. 

• If another user has readied the domain for exclusive use, you cannot ready the 
domain. 

• If another user has readied the domain for protected use, you can ready the 
domain only for read access. 

• You cannot specify the shared access option for a domain that uses an RMS 
sequential data file. 

• If a conflict occurs between the access mode and the access option specified 
(such as trying to ready an RMS sequential file for protected write), 
DATATRIE VE automatically readies the domain with the exclusive access 
option. 

• RMS does not enforce the exclusive access option when you combine it with the 
read access mode. 

Results 

• DATATRIE VE gives you access to the domain with the access option and 
access mode specified. 

• If you do not specify an alias for the domain, you must use the domain name in 
commands and statements that operate on the domain. 

• If you specify an alias for the domain name, DATATRIEVE assigns the alias to 
the domain. You must then use the alias in commands and statements that 
operate on the domain. Once you have assigned an alias to a domain, you can- 
not access the domain by its domain name (the name by which it is catalogued 
in your dictionary) until you finish the alias with the FINISH command or exit 
from DATATRIEVE. 

• If you do not specify an access option for a domain, DATATRIEVE readies the 
domain with the default option, protected. With protected access, other users 
can have read access to the domain, but not write, modify, or extend access. 

• If you do not specify an access mode for a domain, DATATRIEVE readies the 
domain for default access, read. With read access, you can retrieve records, but 
you cannot store, modify, or erase them. 
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• If you want to ready a domain that is already readied, the following rules 
apply: 

- You must use the same alias to ready the domain again. 

- The access option and access mode specified in the new READY command 
replace those previously in effect. 

- DATATRIEVE preserves your collections for domains based on RMS files. 

- Any changes you have made to the record definition associated with the 
domain do not take effect until you finish the domain and ready it again. 

Usage Notes 

• Use the SHOW READY command to show readied domains. The SHOW 
READY command displays the name, file type, access option, access mode, and 
dictionary name of all readied domains. The most recently readied domain is at 
the top of the displayed list. 

• The access mode specified in the READY command determines the operations 
you can perform on the domain. Table 5-18 lists the access modes needed for 
statements that operate on domains. Use the SHOW READY command to 
make sure you have readied the target domain with the appropriate access 
mode. 

Table 5-18: Access Modes Required by DATATRIEVE Statements 



Statement 


Access Mode Required 


ERASE 


Write 


FIND 


Modify, read, or write 


MODIFY 


Modify or write 


PRINT 


Modify, read, or write 


REPORT 


Modify, read, or write 


SORT 


Modify, read, or write 


STORE 


Write or extend 


SUM 


Modify, read, or write 



• When specifying access options for a domain, impose as few restrictions on 
other users as the needs of your task allow. If you specify exclusive access, no 
other user can access the domain. 

• If you must specify a password to get access to the domain, use the asterisk to 
prevent the password from being displayed on your terminal. After you enter 
the READY command, DATATRIEVE prompts for the password but does not 
echo the characters on your terminal. 
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• If you specified a password prompt in the domain definition, DATATRIE VE 
prompts for the password when you ready the domain and uses your response 
to search the entries of the access control list of the record definition to deter- 
mine what privileges you have to the record definition (see Example 3). 

If a password is used in the record definition, it must match the password in the 
dictionary. The password in the domain definition is independent of the pass- 
word in the record definition. 

• A domain stays ready until you release it with the FINISH command or end 
your DATATRIE VE session with EXIT or CTRL/Z. FINISH ends your control 
over a domain, releases the collections of records from that domain, allows 
other users access to the domain in any access mode, and frees the computer 
resources used by the domain. 

• If you redefine the format of the record associated with a readied domain, the 
change in the record definition does not take effect until you use the FINISH 
command to finish the domain and the READY command to ready it again. If 
you just ready the domain again, the new record definition does not take effect. 

• If you want to change a record definition or the type of file organization of a 
domain's data file without redefining the domain, follow these steps to define a 
new data file, and transfer the data with the STORE statement: 

1. Ready the domain as an alias: 

DTR> READY YACHTS AS OLD- YACHTS© 
DTR> SHOW READY© 
Read y d o m a i n s : 

OLD-YACHTS: RMS INDEXED t PROTECTED READ 

DTR> 

2. Change the record definition with the DEFINE RECORD command, if you 
wish. 

3. Define a new data file for the domain, but do not use the SUPERSEDE 
option; this creates a new version of the file associated with the readied 
domain. This does not interfere with the link between the readied domain 
and the original version of the data file: 

DTR> DEFINE FILE FOR YACHTS KEY = TYPE (NODUP)© 
DTR> 

4. Ready the domain as a different alias and specify WRITE access mode. This 
READY command uses the new record definition, if you made one, and 
opens the new data file created by the DEFINE FILE command: 

DTR> READY YACHTS AS NEW_ YACHTS WRITE© 
DTR> SHOW READY© 
Read y d omai n s : 

NEW-YACHTS: RMS INDEXED t PROTECTED WRITE 

OLD_YACHTS: RMS INDEXED » PROTECTED READ 
DTR> 
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5. Use a FOR loop to move the data from the original data file associated with 
OLD_YACHTS to the new one associated with NEW_ YACHTS. 
DATATRIEVE transfers data from fields in the original data file into fields 
with the same names in the new data file: 

DTR> SET NO PROMPT© 

DTR> FOR A IN OLD-YACHTS® 

DTR > STORE B IN NEW YACHTS USING B * BOAT = A ♦ BOAT® 

DTR> 

Examples 

Ready the domain YACHTS for WRITE access: 

DTR > READY YACHTS WRITE® 

Ready the domain PHONES for EXTEND access. The domain definition includes 
a password: 

DTR > READY PHONES <*) EXTEND® 
Enter password for PHONES: ® 
DTR > 

Define a domain with a password prompt. Then ready the domain and respond to 
the password prompt. Note that DATATRIEVE does not echo the password you 
enter: 

DTR > DEFINE DOMAIN PROMPT-YACHTS USING YACHTU) ON YACHT 5® 
DTR> READY PROMPT-YACHTS AS PYTS® 
Enter password for YACHT: ® 

DTR > 
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5.43 REDEFINES Clause 

Function 

Provides an alternate way to define a field. 
Format 



level-no field-name- 1 REDEFINES field-name-2 



Arguments 

level-no 

Is the level number of field name 1. Although not a part of the REDEFINES 
clause, the level number is shown in the format to clarify its position relative 
to the clause. 

field-name- 1 

Is the name of the REDEFINES field. Use this name when you want to refer 
to this field. Although not a part of the REDEFINES clause, the field name is 
shown in the format to clarify its function and its position relative to the 
clause. 

field-name-2 

Is the name of the field being redefined. 

Restrictions 

• The field to be redefined (field name 2) must appear in the record definition 
before its REDEFINES field (field name 1). Both fields must have the same 
level number. 

• The definition of field name 2 cannot contain a REDEFINES clause. However, 
it can be subordinate to a group field with a REDEFINES clause. 

• Neither field name 1 nor field name 2 can be defined with, or contain, a field 
defined with an OCCURS... DEPENDING clause. 

• Neither field name 1 nor field name 2 can contain a COMPUTED BY clause. 
You cannot redefine a COMPUTED BY field. 

• In the definition of field name 1, the REDEFINES clause must immediately fol- 
low the field name. No other clause can be used between the field name and the 
keyword REDEFINES. 

• The REDEFINES field cannot describe an area larger than the area of field 
name 2. However, the area can be smaller than that of field name 2. 
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Result 

The REDEFINES clause provides an alternate definition for an elementary or 
group field. The redefinition refers to the same area of the record as the original 
definition, but it uses the content of the field in a different way. 

Usage Note 

If you need to refer to parts of a numeric field as well as the field itself, you can 
redefine the field as a group field. The subordinate fields of the group fields would 
contain the parts of the numeric field value that you will refer to. Thus, the 
REDEFINES clause allows you to redefine a numeric field as a group field. A 
group field cannot be numeric; a group field is always alphanumeric. 

Example 

The following record definition shows a redefinition of the field 
PART_NUMBER, a numeric field containing 10 digits. Two group fields redefine 
PART_ NUMBER: PART_NUMBER_PARTS and PART_NUMBER_ GROUPS. 
Each redefinition specifies a group field containing a total of 10 digits (the total 
number of digits in all subordinate fields): 

05 PART-NUMBER PIC 9(10), 

05 PART_NUMBER_PARTS REDEFINES PART-NUMBER » 

07 PRODUCT-GROUP PIC 99, 

07 PRODUCT-YEAR PIC 99, 

07 ASSEMBLY-CODE PIC 9. 

07 SUB-ASSEMBLY PIC 99, 

07 PART-DETAIL PIC 999, 
05 PART_NUMBER_GROUPS REDEFINES PART-NUMBER. 

07 PRODUCT_GROUP_ID PIC 9(4), 

07 PART_DETAIL_ID PIC 9(6). 

In this example, the field PRODUCT- GROUP refers to the most significant dig- 
its of PART_ NUMBER and PART_DETAIL to the least significant digits. 
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5.44 RELEASE Command 

Function 

Ends your control over one or more collections, tables, or global variables and 
frees the workspace they occupy. 



Format 





" collection-name " 




RELEASE 


table-name 


[-•] 




variable-name 





Arguments 

collection-name 

table-name 

variable-name 

Is the name of a collection, a dictionary table, or a variable you want to 
release. 

Restrictions 

• You must use this command at DATATRIEVE command level, indicated by 
the DTR> prompt. 

• You must specify at least one collection, table, or variable. There are no 
defaults. 

Results 

• DATATRIEVE releases the specified collections, dictionary tables, and 
variables, freeing the workspace they occupied. The effect is very much like the 
FINISH command. 

• Records and domains associated with collections named in the RELEASE com- 
mand are not affected by the command. 

• If you specify more than one item in the command, DATATRIEVE releases the 
items in left- to-right order. If the command fails before all items are released, 
DATATRIEVE prints a message indicating which item could not be released. 
In such a case, DATATRIEVE releases all items in the command preceding the 
one that failed and does not release the ones that follow it. 
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Usage Notes 

• Before you use the RELEASE command, use the SHOW command to see what 
collections, tables, and variables you have in your workspace: 

- SHOW COLLECTIONS shows the collections you have established and the 
order in which you created them. 

- SHOW TABLES shows dictionary tables you have accessed. 

- SHOW FIELDS shows global variables you have created. 

• When you have two or more collections in your workspace and you release the 
CURRENT one, the collection you formed most recently becomes the new 
CURRENT collection. 

• The RELEASE command is implicit in the following cases: 

- When a FIND statement successfully forms a collection, DATATRIEVE 
releases an existing collection with the same name. If the CURRENT collec- 
tion has no other name, a new collection formed by a FIND statement 
releases and replaces the previous CURRENT collection. DATATRIEVE 
releases the previous collection, even if the new collection contains no 
records. 

- When you type EXIT or CTRL/Z to end a DATATRIEVE session, 
DATATRIEVE releases all collections, dictionary tables, and global 
variables. 

- When you use a FINISH command, DATATRIEVE releases all collections 
associated with the specified domain or domains. 

- When you declare a global variable that has the same name as one that 
exists, DATATRIEVE releases the old global variable. 

• You cannot assign a value to or retrieve the value from a global variable that 
you have released. You can redefine the variable with the DECLARE state- 
ment. If you do, the previous value is lost and the variable is initialized to zero 
if numeric or blank if alphanumeric. 

Examples 

Release one of two named collections, then release the other: 

DTR> set NO PROMPT® 

DTR> FIND SMALL-ONES IN YACHTS WITH LOA < 20© 
1 2 records found! 

OTR> FIND BIG_0NES IN YACHTS WITH LOA > 40© 
£8 records found] 

°TR> SHOW COLLECTIONS© 
Collections: 

BIG-ONES (also CURRENT) 

SMAL1 ONES 

(continued on next page) 



5-178 Commands, Statements, and Definition Clauses 



RELEASE 

Continued 



DTR> RELEASE BIG_ONES© 
DTR> SHOW COLLECTIONS© 
Collections: 

SMALL-ONES (also CURRENT ) 
DTR> RELEASE SMALL-ONES© 
DTR> SHOW COLLECTIONS© 
No established collections 
DTR> 

Release the dictionary table DEPT_TABLE and the global variables, DEPT and 
NEW_DEPT: 

DTR> DECLARE DEPT PIC XX,© 
DTR> DECLARE NEW-DEPT PIC XX.© 
DTR> DEPT = "CE"© 
DTR> NEW-DEPT = "SD"© 

DTR> PRINT DEPT VIA DEPT-TABLE USING T(20)© 

DEPT 

Commercial 
Engineering 

DTR> PRINT NEW-DEPT MIA DEPT-TABLE USING T(20)© 

NEW 
DEPT 

Sales Department 

DTR > SHOW TABLES® 
Tables loaded: 

DEPT-TABLE 

Tables: 

DEPT-TABLE 

DTR> SHOW TABLES© 
Tables : 

DEPT-TABLE 
DTR > SHOW FIELDS© 
Global variables: 

NEW-DEPT [Character string] 

DEPT [Character string 
DTR > RELEASE DEPT© 
DTR > SHOW FIELDS© 
Global variables: 

NEW_DEPT [Character string] 

DTR > RELEASE NEW-DEPT© 
DTR> SHOW FIELDS© 

No Domains Readied or Global Variables Declared 
DTR> 



R I G_TABLE 



RIG_TABLE 
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5.45 REPEAT Statement 

Function 

Causes DATATRIEVE to execute a simple or compound statement a specified 
number of times. 

Format 



REPEAT value-expression statement 



Arguments 

value-expression 

Is a value expression indicating the number of times to execute the state- 
ment. This argument must evaluate to a positive, integer less than or equal 
to 32,767. 

statement 

Is any simple or compound DATATRIEVE statement except a FIND, 
SELECT, DROP, or SORT statement. 

Restrictions 

• Do not use a FIND, SELECT, DROP, or SORT statement in a REPEAT 
statement. 

• You must observe all restrictions on the statements you use in a REPEAT 
statement. 

• If the REPEAT statement invokes a procedure (for example, REPEAT n 
:procedure-name), the procedure cannot contain a command or a FIND, 
SELECT, DROP, or SORT statement as its first element. 

• If a compound statement in a REPEAT statement invokes a procedure (for 
example, REPEAT n BEGIN :procedure-name; END), that procedure cannot 
contain a DATATRIEVE command or a FIND, SELECT, DROP, or SORT 
statement as its first element. 

Results 

• DATATRIEVE executes the statement the number of times specified by the 
value expression. Then DATATRIEVE executes the command or statement 
following the REPEAT statement. 

• If a REPEAT statement invokes a procedure, DATATRIEVE executes only the 
first statement (whether simple or compound) in the procedure the number of 
times specified in the value expression. Each succeeding statement in the pro- 
cedure is executed only once and is not part of the REPEAT statement. This is 
why the first element of a procedure cannot be a command or a FIND, 
SELECT, DROP, or SORT statement. 
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Usage Notes 

• Use the REPEAT statement to repeat a simple or compound statement a fixed 
number of times. 

• To force an exit from a loop created by a REPEAT statement, take one of the 
following actions: 

— Type CTRL/Z in response to any prompt within the loop. 

- Type CTRL/C at any time during the execution of the statement (but not in 
response to a prompt). 

• To control a REPEAT statement loop, use an IF-THEN-ELSE statement with 
an ABORT statement in the THEN or ELSE clause. Put the IF statement in a 
BEGIN-END block in the REPEAT statement. 

• Having SET ABORT or SET NO ABORT in effect does not change 
DATATRIE VE's response to an ABORT statement in a REPEAT statement 
loop. When the conditions for the ABORT statement are true, DATATRIE VE 
ends the REPEAT statement, does not execute any statements following the 
ABORT statement, and returns you to DATATRIEVE command level. 

• You can nest REPEAT statements. DATATRIEVE executes each inner 
REPEAT statement the specified number of times each time it loops through 
the outer REPEAT statement. 

Examples 

Print "TEST REPEAT" three times: 



DTR> REPEAT 3 PRINT "TEST REPEAT "(ret) 
TEST REPEAT 
TEST REPEAT 
TEST REPEAT 



DTR> 



Exit from a REPEAT statement by responding to a prompt with a CTRL/Z: 

DTR> READY YACHTS WRITE© 

DTR> REPEAT 5 STORE YACHTS© 

Enter MANUFACTURER: HQBIE© 

Enter MODEL: CAT© 

Enter RIG: SLOOP© 

Enter LENGTH-OUER-ALL: 22© 

Enter DISPLACEMENT: aOOO© 

Enter BEAM: 8© 

Enter PRICE: G50Q© 

Enter MANUFACTURER: - z 

Execution terminated by operator 

DTR> FIND YACHTS WITH BUILDER = " HOB I E "© 

C i record found] 

DTR> 
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Show the effect of nesting REPEAT statements in procedures. The procedure 
NUM1 contains two PRINT statements. The procedure NUM2 contains two 
REPEAT statements, one nested in the other. The inner REPEAT statement 
causes DATATRIEVE to execute the first PRINT statement in NUM1 twice each 
time DATATRIEVE loops through the outer REPEAT statement: 

DTR> SET NO PROMPT© 
DTR > SHOW NUMl© 
PROCEDURE NUM1 

PRINT SKIP* "ONE* TWO > THREE" 
PRINT "ONE * TWO* THREE* FOUR, FIVE" 
END-PROCEDURE 
DTR > :NUM1© 

ONE* TWO* THREE 

ONE* TWO * THREE* FOUR* FIVE 

DTR> SHOW NUM2(ret) 
PROCEDURE NUM2 
REPEAT 2 

BEGIN 

REPEAT 2 :NUM1 

END 

:NUM1 

END_ PROCEDURE 
DTR > :NUM2(RET) 

ONE* TWO * THREE 

ONE * TWO * THREE 

ONE* TWO* THREE, FOUR* FIVE 

ONE , TWO * THREE 

ONE* TWO, THREE 

ONE, TWO* THREE* FOUR* FIVE 



ONE , TWO * THREE 

ONE* TWO * THREE* FOUR* FIVE 

DTR > 
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5.46 REPORT Statement 

Function 

Invokes the Report Writer and is the first entry in a report specification. You 
specify the data to go in the report and the output device for the report. You 
specify attributes of the report with Report Writer statements, listed in Table 
5-19 and described in this section, and end the report specification with the 
END_REPORT statement. 

Format 



REPORT [rse] ON file-spec 

*. prompt 



Arguments 

rse 

Specifies the data for the report. You can report on readied domains, collec- 
tions, and lists. 

ON 

Specifies that the report is to be written to a file or displayed on a terminal. 
When you specify ON, the Report Writer inserts a form feed at the end of the 
report. If you specify ON when displaying a report on a video terminal, the 
last page of the report scrolls off the screen. 

file-spec 

Is the file to which you want to write the report. The file specification must 
have this format: 

For RSTS/E systems: dev:[PPN]file-name.type 

For RSX systems: dev:[UIC]file-name.type;ver 

You must specify at least one field in the file specification. On RSTS/E sys- 
tems, you must specify a file name. DATATRIEVE uses the following defaults 
for fields not specified: 



Field 


Default 


dev: 


SY: (the system device) 


[UIC/PPN] 


Your default UIC/PPN 


file name 


Null string 


type 


.LST 


;ver 


1 or next higher version 




(non-RSTS/E systems only) 
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*. prompt 

Is a prompting value expression that allows you to specify a file specification 
when DATATRIEVE processes the report specification. 

Restrictions 

• If you specify another terminal as the device to display your report, that termi- 
nal cannot be logged in to the system or attached by another user. 

• To send your report to a tape drive, you must mount a tape and allocate the 
tape drive before specifying the tape drive in the REPORT statement. 

Results 

• DATATRIEVE writes the report to the specified file and prompts for Report 
Writer statements with the RW> prompt. Table 5-19 describes Report Writer 
statements. To end the report specification., use the END_REPORT statement. 



Table 5-1 9: Summary of Report Writer Statements 



Statement 


Function 


AT BOTTOM 


Specifies the value, position, and format of the print objects in the header lines 
and summary lines displayed at the bottom of reports, report pages, and control 
groups 


AT TOP 


Specifies the value, position, and format of the print objects in the header lines 
and summary lines displayed at the top of reports, report pages, and control 
groups 


END_REPORT 


Ends a report specification 


PRINT 


Controls the content, format, and column headers for the detail lines in a report 


SET 


Controls the report header (name, date, format of data, and page numbering), 
and defines the size of report pages and the length of the report 



• When you omit the ON clause in a REPORT statement, DATATRIEVE dis- 
plays the report on your terminal. 

• When you omit the RSE, the Report Writer uses the data in your current col- 
lection for the report. If there is no current collection, DATATRIEVE displays 
the error message "A current collection has not been established. " 



Usage Notes 

• You can write a report to a file in any directory to which you have write access. 

• To report on sorted records, form a sorted collection and specify the name of 
the collection in the REPORT statement. If you specify a SORTED BY 
clause in an RSE in the REPORT statement, DATATRIEVE- 11 may display 
the error "Sort work space exhausted" without creating the report. 
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• You can report on data only in domains readied for READ, WRITE, or 
MODIFY access. Because you cannot establish collections or record streams in 
domains readied for extend access, you cannot report on data in domains read- 
ied for extend access. 

• The data you report must be contained in the current collection or in the record 
stream established by the RSE in the REPORT statement. 

• If you make a typing error or syntax error in a Report Writer statement, 
DATATRIE VE will display an error message and return you to DATATRIEVE 
command level. If you have entered the Report Writer statements interactively 
in response to the RW> prompt, you must retype all the statements again to 
correct the error. To avoid having to retype Report Writer statements, create a 
command file or define a procedure that contains your Report Writer state- 
ments. If DATATRIEVE detects typing or syntax errors in Report Writer 
statements in a command file or procedure, you can simply edit the command 
file or procedure and correct the errors without retyping the entire sequence of 
statements. 



Examples 

Write a report to display on your terminal: 



DTR> SET NO PROMPT© 
DTR > READY YACHTS© 

DTR> REPORT YACHTS WITH BUILDER = " ALB I N "(ret) 
RW> SET REPORT_NAME = "YACHTS BY ALB I N "(ret) 
RW> PRINT BOAT© 
RW> END_REPORT© 
DTR > 



Define a procedure that writes a report on a group of yachts to a file in your 
default directory: 

DTR > SET NO PROMPTS!) 
DTR > READY YACHTS© 
DTR > SHOW YACHT_REPO R T© 
PROCEDURE YACHT-REPORT 

DECLARE B PIC X< 10) . 

REPORT YACHTS WITH BUILDER = *. "Builder to report on"ON *."file name 
SET REPORT-NAME = *. "Report name" 
SET COLUMNS-PAGE = 70 
PRINT BOAT 

AT BOTTOM OF REPORT PRINT SKIP* COL 10 , 

"BOAT COUNT:"* SPACE t COUNT (-) USING IS* 
COL 45, "AVERAGE PRICE: " t AVERAGE PRICE 
END-REPORT 
END-PROCEDURE 
DTR > : YACHT-REPORT© 

Enter Report name: "YACHTS BY GRAMPIAN "© 
Enter Builder to report on: GRAMPIAf 
Enter file name: GRAMPIAN. DAT© 
DTR > 
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The data file produced by this report specification looks like this: 







YACHTS BY 


GRAMPIAN 




15-Feb-8 












Pase 1 








LENGTH 












OVER 






MANUFACTURET 


? MODEL 


RIG 


ALL 


WEIGHT BEAM 


PRICE 


GRAMPIAN 


2-34 


SLOOP 


34 


1 1 1 800 10 


$29 ,675 


GRAMPIAN 


2B 


SLOOP 


26 


5 » GOO 08 


$11 >495 


GRAMPIAN 


28 


SLOOP 


28 


GfSOO 10 


$14 ,475 


GRAMPIAN 


30 


SLOOP 


30 


SfBOO 03 


$17 »775 


GRAMPIAN 


34 


KETCH 


33 


12*000 10 


$29 »675 


BOAT 


COUNT: 5 




AVERAGE PRICE: 


$20 ,619 



See the D AT ATRIEVE -11 Guide to Writing Reports for more information on 
writing reports and for more examples. 



5.46.1 AT BOTTOM Statement (Report Writer) 
Function 

Specifies the value, position, and format of the print objects in the header lines 
and summary lines displayed at the bottom of reports, report pages, and control 
groups (groups of sorted records with the same value in one or more fields). 



Format 





( REPORT ) 




AT BOTTOM OF 


< PAGE > 


PRINT summary-element [,...] 




( field-name ) 





Arguments 

REPORT 

Displays the summary line at the bottom of the last page of the report. 
PAGE 

Displays the summary line at the bottom of each page of the report, 
field-name 

Establishes a pattern of control breaks for the entire report, dividing the 
report into groups of records with a common value for the field. Displays the 
summary line at the bottom of the control group for which the field name is 
the sort key. 

summary-element 

Specifies the value, position, and format of the fields. Table 5-20 summarizes 
the summary elements that can be used with AT BOTTOM statements. 
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Table 5-20: Report Writer AT BOTTOM Statement: Summary Elements 



Summary Element 


Function 


Usage Notes 


AVERAGE 


Displays the average value of the 
value expressions 


Calculated for the detail lines 
of the report, page, or group 


COLn 


Specifies where the output of the 
next element begins 


Same usage as in the Report 
Writer PRINT statement 


COUNT 


Displays the number Calculated 
for of detail lines the detail lines 
of the report, page, or group 
specified 


Displays the number Calcu- 
lated for of detail lines the 
detail lines of the report, page, 
or group specified 


field-name [modifier] 


Prints the common value for a 
control group 


Same usage as in the Report 
Writer PRINT statement 


MAX [value-expression] 


Displays the maximum value of 
the value expressions 


Calculated for the detail lines 
of the report, page, or group 
specified 


MIN [value-expression] 


Displays the minimum value of 
the value expressions 


Calculated for the detail lines 
of the report, page, or group 

QDPPlfipd 


NEW_PAGE 


Starts a new page before the out- 
put of the next summary 
element 


Same usage as in the Report 
Writer PRINT statement 


NEW_SECTION 


Starts a new page and a new 
sequence of page numbers, 

ci n nine witVi v\£\ rvnp 

L^C^gXlXXlJ.Xlg Willi UugC vllC 


Can be used only in AT TOP 
and AT BOTTOM statements 


SKIP [n] 


Prints the next element n lines 
from the current line 


Same usage as in the Report 
Writer PRINT statement 


SPACE [n] 


Inserts n spaces between the out- 
put of the preceding and follow- 
ing elements 


Same usage as in the Report 
Writer PRINT statement 


TAB [n] 


Inserts the space of n tab charac- 
ters before the output of the next 
element 


Same usage as in the Report 
Writer PRINT statement 


TOTAL [value-expression] 


Displays the total of values for 
the expressions 


Calculated for the detail lines 
of the report, page, or group 
specified 


value-expression 


Displays the value in a summary 
line 


Same usage as in the Report 
Writer PRINT statement 
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Restrictions 

• You can use the AT BOTTOM statement only with sort keys. If you specify a 
field not included in the sort order, the Report Writer displays an error mes- 
sage and does not produce the report. 

• Do not specify AT BOTTOM OF PAGE PRINT NEW- PAGE. 
Results 

• The AT BOTTOM statement calculates and summarizes information con- 
tained in the records of the page, group, or report specified in the statement. 

• When you specify AT BOTTOM OF field-name PRINT field-name, the Report 
Writer prints the value in the specified field of the last detail line in the control 
group. 

Usage Notes 

• DATATRIE VE checks the sort order of the collection or record stream you 
want to report. You can establish a sort order with the FIND, SORT, or 
REPORT statements. 

• If you specify AT BOTTOM OF field-name without having sorted the records, 
the Report Writer divides the detail lines into control groups anyway. A new 
control group is formed every time the value in the specified field changes. If no 
values in that field are repeated in consecutive detail lines, the Report Writer 
treats each line as a separate control group and prints the header and sum- 
mary lines above and below each line as indicated in the record specification. 

• If the records are already sorted according to an indexed key and there is only 
one level of control break, the Report Writer divides the control groups at the 
appropriate places. If you want multiple levels of control groups, you must sort 
the records in advance with a FIND, SORT or REPORT statement. 

5.46.2 AT TOP statement (Report Writer) 
Function 

Specifies the value, position, and format of the print objects in the header lines 
and summary lines displayed at the top of reports, report pages, and control 
groups (groups of sorted records with the same value in one or more fields). 



Format 



AT TOP OF 



{REPORT ) 
PAGE > PRINT 
field-name J 



header-element 
summary-element 



[.-] 
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Arguments 

REPORT 

Displays the header line or summary line above the detail lines on the first 
page of the report and suppresses the report header on the first page of the 
report. The report header is displayed on the following pages of the report, 
and the page numbers begin with Page 1 on the second physical page of the 
report. To specify a title page for your report, end the print list with a 
NEW_PAGE or NEW_SECTION statement. 

PAGE 

Displays the header line or summary line at the top of each page of the report, 
and replaces the report header on every page. 

field-name 

Establishes a pattern of control breaks for the entire report, dividing the 
report into groups of records with a common value for the field. Displays the 
header line or summary line at the top of the control group for which the field 
name is the sort key. 

header-element 
summary-element 

Specifies the value, position, and format of the fields. Table 5-21 summarizes 
the header and summary elements that can be used with AT TOP statements. 



Table 5-21 : Report Writer AT TOP Statement: Header and Summary Elements 



Header or 
Summary Element 


Function 


Usage Notes 


AVERAGE 


Displays the average value of the 
value expressions in the record 
stream or the current collection 


Does not indicate the average 
for the detail lines of the report, 
page, or control group specified 


COLn 


Specifies where the output of the 
next header or summary ele- 
ment begins 


Same usage as in the Report 
Writer PRINT statement 


COLUMN _HEADER 


Displays the column headers 
denned by the PRINT statement 
and AT statements 


Overrides the suppression of 
column headers for AT TOP OF 
REPORT or PAGE 


COUNT 


Displays the number of records 
in the record stream or current 
collection 


Does not indicate the number 
of detail lines of the report, 
page, or control group specified 


field-name [modifier] 


Prints the common field value at 
the top of each control group 


Same usage as in the Report 
Writer PRINT statement 



(continued on next page) 
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Table 5-21 : Report Writer AT TOP Statement: Header and Summary Elements (Cont.) 



Header or 
Summary Element 


Function 


Usage Notes 


MAX [value-expression] 


Displays the maximum value of 
all value expressions in the 
record stream or current 
collection 


Does not indicate the maxi- 
mum values for the detail lines 
of the report, page, or control 
group specified 


MIN [value-expression] 


Displays the minimum value of 
all value expressions in the 
record stream or current 
collection 


Does not indicate the minimum 
value for the detail lines of the 
report, page, or control group 
specified 


NEW_PAGE 


Starts a new page for the report 


Same usage as in the Report 
Writer PRINT statement 


NEW_SECTION 


Starts a new page and a new sec- 
tion numbered as page one 


Use with AT TOP OF field- 
name to produce a new section 
for each group 


REPORT- HEADER 


Displays the report header, 
including the report name, date, 
and page number 


Overrides the suppression of a 
report header in AT TOP OF 
REPORT or PAGE 


SKIP [n] 


Prints the next header or sum- 
mary element n lines from the 
current line 


Same usage as in the Report 
Writer PRINT statement 


SPACE [n] 


Inserts n spaces between the out- 
put of the preceding and follow- 
ing elements 


Same usage as in the Report 
Writer PRINT statement 


TAB [n] 


Inserts the space of n tab charac- 
ters before the output of the next 
element 


Same usage as in the Report 
Writer PRINT statement 


TOTAL [value-expression] 


Displays the total for the value 
expressions in the record stream 
or current collection 


Does not indicate the total for 
the detail lines of the report, 
page, or control group specified 


value-expression 


Displays the value in a header or 
summary line 


Same usage as in the Report 
Writer PRINT statement 



Restrictions 

• You can use the AT TOP statement only with sort keys. If you specify a field 
not included in the sort order, the Report Writer displays an error message and 
does not produce the report. 

• Do not specify AT TOP OF PAGE PRINT NEW_PAGE. 
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Result 

An AT TOP statement summarizes information for the entire group of records in 
the record stream or in the current collection, not the records of the page, group, 
or report specified in the statement. 

Usage Notes 

• The header and summary elements may contain modifiers to specify edit 
strings or to suppress headers. 

• DATATRIE VE checks the sort order of the collection or record stream you 
want to report. You can establish a sort order with the FIND, SORT, or 
REPORT statements. 

• If you specify AT TOP OF field-name without having sorted the records, the 
Report Writer displays a warning message and divides the detail lines into 
control groups anyway. A new control group is formed every time the value in 
the specified field changes. 

5.46.3 END-REPORT Statement (Report Writer) 
Function 

Ends a report specification. 
Format 



END-REPORT 



Usage Notes 

• The END_REPORT statement must be the last statement in the report 
specification. 

• Following the END_REPORT statement, the Report Writer takes one of the 
following courses of action: 

— Prompts you for any values you specified with the *. prompt in the record spe- 
cification and then produces the report. 

- Produces the report and sends it to the device or file you have specified in the 
REPORT command. 
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5.46.4 PRINT Statement (Report Writer) 

Function 

Specifies the following characteristics of the detail lines in a report: 

• The content of the detail lines: field values, other values, and text strings 

• The format of fields in the detail lines: order, column position, and edit string 
to be be used for print items 

• The column headers for the print items in the detail line 
Format 



PRINT print-list-element [,...] 



Argument 

print-list-element 

Specifies values, position, and format of the print items in the detail line. 
Table 5-22 indicates the parameters of the report controlled by various print 
list elements and modifiers. 

Restrictions 

• You can include only one PRINT statement in a report specification. If the 
report specification contains no AT statements, it must contain a PRINT state- 
ment. If your report specification contains an AT statement, then it does not 
have to contain a PRINT statement. 

• Unlike the DATATRIEVE command level PRINT statement, the Report 
Writer PRINT statement must be followed by at least one print list element. If 
you do not specify a print list element, the Report Writer prompts for one. 

Result 

The PRINT statement formats the detail lines of a report according to the print 
list elements and modifiers specified. Table 5-22 lists and describes the print list 
elements you can use with the Report Writer PRINT statement. Table 5-23 lists 
and describes print list modifiers. 
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Table 5-22: Report Writer Print List Elements 



Print List Element 


Function 


Content of Detail Line: 




field-name [modifier] 


Can include elementary, group, list, REDEFINES, or COM- 
PUTED BY fields; to print all fields, specify the top-level field 
name 


value-expression [modifier] 


Can be a related value expression derived from field values using 
arithmetic operators or a literal or variable 


Format of a Detail Line: 




COLn 


Specifies where the output of the next print list element begins 


TAB [n] 


Inserts the space of n tab characters before the output of the next 
nvint li'sit plpmpnt 


SKIP [n] 


Begins printing the next print list element n lines from the cur- 
rent line 


SPACE [n] 


Inserts n spaces between the output of the preceding and follow- 
ing print list elements 


Beginning of New Page: 




NEW_ PAGE 


Causes the Report Writer to start a new report page 



Table 5-23: Report Writer Print List Modifiers 



Print List Modifier 


Function 


Column Headers for Print Items: 




("header-segment"[/. . .]) 


Specifies one or two character string literals to be displayed as 
headers for the preceding field or value expression, overriding 
the field name or query header from the field definition. The 
entire modifier must be enclosed in parentheses and must 
immediately follow its associated field name or value 
expression. 


H 


Suppresses the printing of the query header or field name 
associated with the field in its record definition 


Format of the Detail Line Item: 




USING edit-string 


Imposes the characteristics of the specified edit string on the 
preceding field or value expression. The edit string must con- 
form to the rules for the EDIT. STRING clause. 
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Usage Notes 

• If the value specified in the COL list element is too small to accommodate all 
the fields, the Report Writer carries the overflow fields onto the next line. The 
Report Writer does not split fields between lines, but the column headers of the 
overflow fields may be lost. 

• You can list print list elements and their modifiers in any order you choose. 

• When the data you are reporting includes a list, use an inner print list element 
(ALL [print-list] of rse) in the PRINT statement to specify the value, position, 
and format for fields in the list. Each item of the list takes at least one physical 
line of printing. 

• If you do not specify positions or edit strings for any of the fields in a detail line, 
the Report Writer determines the format for those fields using these criteria: 

— The edit string in the field definition, if present, determines the format for 
the field. 

— If the field definition has no edit string, the PICTURE clause determines the 
format for the field. 

— If the field definition has neither an edit string nor a PICTURE clause, the 
Report Writer invents a picture clause to accommodate the data in the field. 

To gain full control over the formats of the fields of your detail lines, explicitly 
define edit strings with the USING edit string modifier. 

5.46.5 SET Statement (Report Writer) 
Function 

Controls the report header and defines the size of report pages and the length of 
the report. With Report Writer SET statements, you can specify: 

• The report header: the report name, the date, the format of data, and page 
numbering 

• The size of report pages: the number of columns and the number of lines per 
page 

• The length of the report: the maximum number of lines and the maximum 
number of pages 
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Format 



For naming the report: 
SET REPORT-NAME = 



("string"[/...U 
( *. prompt J 



For specifying a date or string at the upper right of each page: 
SET DATE = "string" 

For controlling the printing of a date or page number: 



j NO DATE 
SET NUMBER 

( NO NUMBER 



[,-] 



For specifying page width or length, or overall report length: 



SET 



COLUMNS-PAGE = 
LINES-PAGE = 
MAXJJNES = 
MAX_PAGES = 



prompt 



[,-] 



Arguments 

Table 5-24 summarizes information about each type of Report Writer SET 
statement: 



• The first three columns indicate the argument, the function of the statement, 
and the Report Writer's default setting if the statement is not used. 



• The "Prompt Option" column indicates whether or not you can specify a 
prompting value expression with a form of the SET statement. If you include a 
prompt, the Report Writer prompts you for a value when it processes the report 
specification. 

• The "Maximum Value" column indicates the largest value you can specify for a 
form of the SET statement. 
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Table 5-24: Report Writer SET Statement Arguments 



Argument 


Function 


Default 


Prompt 
Option 


Maximum 
Value 


REPORT. NAME 


Specifies a name for 
the report and 
centers the name on 
the first line of 
each page 


No report 
name 


Yes 




DATE 


Specifies a date or 
string and prints it 
on the upper right 
line of each page; NO 
DATE suppresses the 
printing of the 
current date 


Current 

system 

date 


No 


- 


(NO) NUMBER 


Causes the Report 
Writer to print a 
page number below the 
date; NO NUMBER 
suppresses the 
printing of page 
numbers 


Current 

page 

number 


No 




COLUMNS- PAGE 


Specifies the page 
width in columns 


Current 
terminal 
width or 
80 columns 


Yes 


255 


LINES-PAGE 


Specifies the page 
length in lines 


60 lines 


Yes 


32,767 


MAX_ LINES 


Specifies the maximum 
lines for the report 


No limit 


Yes 


32,767 


MAX_ PAGES 


Specifies the maximum 
pages for the report 


No limit 


Yes 


32,767 



Examples 

Many examples of report specifications and reports may be found in the 
DA TA TRIEVE-1 1 Guide to Writing Reports. 
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5.47 SELECT Statement 



Function 



Establishes a selected record for a collection. 



Format 



SELECT 



FIRST 
NEXT 
LAST 



[collection-name] 



value-expression 



Arguments 

FIRST 

Selects the first record in the target collection. 
NEXT 

Selects the next record in the target collection. When you omit a position spe- 
cification, NEXT is the default. 

LAST 

Selects the last record in the target collection, 
value-expression 

Evaluates to a positive number; DATATRIEVE uses the integer part of the 
number to select the record with that position number in the collection. 

collection-name 

Is the name of the target collection containing the record to be selected. If 
omitted, the target collection is the CURRENT collection. 

Restrictions 

• You must establish the target collection with a FIND statement before you can 
use the SELECT statement. 

• The target collection cannot be empty. 

• The SELECT statement can move the collection cursor (which points to the 
selected record in a collection) to the position of a record that has been dropped, 
but you cannot retrieve any data from the record that occupied that position 
before you dropped it. You must form a new collection or record stream con- 
taining that record to retrieve its data. 

• Do not use a SELECT statement in FOR, REPEAT, or WHILE statements. 
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• If you specify a value expression, it must evaluate to a positive number greater 
than or equal to one, and less than or equal to the size of the largest possible 
collection. The size of the largest possible collection is limited by the amount of 
DATATRIEVE work space available. 

• If the integer portion of the evaluated value expression exceeds the number of 
records in the collection, DATATRIEVE displays the error "Record number out 
of range for collection." 

• You cannot use a SELECT statement within a compound statement. 
Results 

• The SELECT statement establishes a selected record in the target collection 
and, thus, establishes a single record context for one record in that collection. 

• The record DATATRIEVE selects depends on the arguments you supply, the 
content of the target collection, and the existence and position of a previously 
selected record in the collection. 

• When you omit the argument that determines the position of the selected 
record, DATATRIEVE responds as though you had entered SELECT NEXT: 

- If you have not established a selected record in a collection and you enter 
SELECT NEXT or SELECT with no argument, the first record in the collec- 
tion becomes the selected record. 

- If the collection cursor (which points to the selected record in a collection) 
points to the last record in the collection and you specify SELECT NEXT or 
SELECT with no argument, DATATRIEVE displays an error message on 
your terminal, and retains the last record in the collection as the selected 
record. 

- If the selected record in the collection is neither first nor last and you specify 
SELECT NEXT or SELECT with no argument, the next record in the collec- 
tion becomes the selected record. 

• If the record identified by the SELECT statement has been dropped from the 
collection with a DROP statement, DATATRIEVE displays a message on your 
terminal and moves the collection cursor to the position of the dropped record. 

• If the target collection is not the CURRENT collection, selecting a record from 
it does not make it the CURRENT collection. 

• When you specify a value expression in a SELECT statement, the positive inte- 
ger to which the expression evaluates is the position number of the one 
selected record in the collection. The integer does not designate the number of 
records selected. For example, if you type SELECT 5, you select the fifth record 
in the target collection, not five records from the collection. 

• If you select a record from the CURRENT collection and then select a record 
from another collection, the CURRENT collection and its selected record 
remain unchanged. 
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Usage Notes 

• Use the SELECT statement to establish a single record context for a record in a 
collection. Having a selected record allows you to retrieve and compare values 
in the fields of a selected record without specifying a target record stream. 
When referring to fields of records in a single record context, you can fre- 
quently use the field names without field name qualifiers, almost as though 
they were variables. 

• When you use a field name by itself in a value expression, its value is retrieved 
from the "nearest" selected record with a field of that name: 

- D ATATRIE VE establishes the "nearness" of selected records based on the 
order in which you created the collections with the FIND statement. The 
most recently created collection is the nearest. 

- The order in which you select records has no effect on relative nearness of 
selected records. 

• Use a SELECT statement to establish a target record for the ERASE and 
MODIFY statements and to establish a target record for PRINT statements in 
which you include only the print list. 

• To show the position of the selected record in the target collection, use the 
SHOW command. This command prints the name of the collection, the name of 
the domain from which the collection is derived, the number of records in the 
collection, the names of fields used to establish the sort order of the collection, 
and the position number of the selected record in the target collection. It also 
tells you if the selected record has been dropped from the collection by a pre- 
vious DROP statement. 

• To show the name and attributes of the CURRENT collection, use the SHOW 
CURRENT command. 

• If you use the SELECT statement to establish a selected record for the current 
collection, you need type only PRINT and press RETURN to display that 
selected record. If the CURRENT collection has no selected record, 

D ATATRIE VE displays on your terminal the selected record from the most 
recently established named collection that has a selected record. 

• If no existing collection has a selected record and you enter a PRINT statement 
without a print list, D ATATRIE VE displays a message on your terminal and 
displays the entire current collection. 
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• To display all fields of the selected record of a named collection that is not the 
CURRENT collection, you must provide a properly qualified top-level field 
name in the print list of a PRINT statement: 

— If you created the collections from the same domain, use the collection name 
as the qualifier. For example, a collection of YACHTS called BIGGIES is not 
the CURRENT collection, and the CURRENT collection has a selected 
record. To display the selected record in BIGGIES, type PRINT 
BIGGIES.BOAT and press RETURN. 

- If you created the collections from different domains, you do not have to 
qualify the top-level field names unless they are the same. If the top-level 
field names of the different domains are the same, you can use the domain 
name to qualify the top-level field names. 

• You can refer to the fields of the selected record as though they were variables. 
DATATRIEVE resolves an unqualified field name to the most recently formed 
collection with a selected record containing a field with that name. To refer to a 
field name beyond the most recently formed collection with a selected record 
containing that same name, you must provide a suitable qualifier to establish 
the appropriate context. Use the name of the collection containing the target 
record as the qualifier. 

• To distinguish between two or more selected records referred to in one complex 
DATATRIEVE statement, use context variables. Context variables can be par- 
ticularly useful if you derived the collections from the same domain and the 
field names of the collections in question are identical. 

• If you want to perform the same set of statements on each record in the 
CURRENT collection, do not use a SELECT statement in a BEGIN-END 
block inside a REPEAT statement. Use the following method to loop through 
the CURRENT collection: 

DTP > SET NO PROMPT© 
DTR> FOR CURRENT© 
DFN> BEGIN© 



DFN> END© 
DTR> 

• See the DATATRIEVE -11 Interactive User's Guide for a discussion of name 
recognition and single record contexts in DATATRIEVE. 

Examples 

Select the last record in the current collection: 

DTR > SET NO PROMPT© 
DTR> READY YACHTS© 
DTR> FIND FIRST 5 YACHTS© 
C 5 records found] 

DTR> PRINT ALL© (continued on next page) 
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PRICE 
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12 
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DTR > SELECT 


LAST© 














DTR> PRINT© 
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ALL 


WEIGHT 
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2G 
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26 
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08 
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DTR> 



Select the fifth record in the collection BIG_ONES: 

DTR > SELECT 5 BIG-ONES© 
DTR > 
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5.48 SET Command 

Function 

• Controls DATATRIE VE's response to ABORT statements 

• Sets the maximum number of columns per page for DATATRIE VE output 

• Establishes your current dictionary 

• Starts DATATRIE VE Guide Mode 

• Starts or stops automatic syntax prompting for continued statements and 
commands 

Format 

SET < 



Arguments 

ABORT 

Causes DATATRIE VE to abort the remainder of a procedure or command file 
when DATATRIE VE executes an ABORT statement, when you enter a 
CTRL/Z to a prompt, or when a syntax or logical error occurs during the 
execution of a command or statement (except the DELETE command). 

NO ABORT 

Causes DATATRIEVE, when processing a procedure or a command file, to 
abort only the one statement containing an ABORT statement it executes. 
SET NO ABORT also causes DATATRIEVE to take the same action when 
you respond with a CTRL/Z to a prompt in a procedure or command file. 
DATATRIEVE then executes the next command or statement in the proce- 
dure or command file. SET NO ABORT is in effect when you start a 
DATATRIEVE session. 

COLUMNS_PAGE = n 

Establishes the number of columns per page for DATATRIEVE output and 
the default page width for the Report Writer. When you start your session, 
the default COLUMNS-PAGE setting is 80. 



ABORT v 

NO ABORT J 

COLUMNS-PAGE = n / 

DICTIONARY file-spec i [,...] 

GUIDE ( 

PROMPT 1 

NO PROMPT / 
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DICTIONARY [file-spec] 

Causes DATATRIEVE to set your current dictionary to the file specified in 
the command. When you start your DATATRIEVE session your current dic- 
tionary is your default dictionary. SET DICTIONARY without a file specifica- 
tion returns you to your default dictionary. 

The file specification must have this format: 

For RSTS/E systems: dev:[PPN]file-name.type 

For RSX systems: dev:[UIC]file-name.type;ver 

You must specify at least one field in the file specification. DATATRIEVE 
uses the following defaults for fields not specified: 

Field Default 

dev: SY: (the system device) 

[UIC/PPN] Your default UIC/PPN 

file name QUERY 

.type .DIC 

;ver 1 or next higher version 

(non-RSTS/E systems only) 



GUIDE 

Starts Guide Mode, the tutorial mode of DATATRIEVE. Refer to the 
Introduction to DATATRIEVE-11 manual for a description of Guide Mode. 

PROMPT 

Causes DATATRIEVE to prompt for elements needed to complete the syntax 
of the current command or statement. When you press RETURN before com- 
pleting a command or statement, DATATRIEVE prompts you for the next 
syntactic element of that statement or command. The prompt takes the form 
of [Looking for element]. At the start of a DATATRIEVE session, SET 
PROMPT is in effect. 

NO PROMPT 

Stops DATATRIEVE from prompting for elements needed to complete the 
syntax of the current command or statement. 



Commands, Statements, and Definition Clauses 5-203 



SET 

Continued 



Restrictions 

• You must enter SET commands at DATATRIEVE command level, indicated by 
the DTR> prompt. 

• You cannot use SET commands in compound statements (THEN, IF-THEN- 
ELSE, and BEGIN-END) or in FOR, REPEAT, or WHILE statements. 

• In the SET COLUMNS_PAGE command, the argument n must be an 
unsigned, nonzero integer less than or equal to 255. 

Results 

• When SET ABORT is in effect and DATATRIEVE is executing a procedure or 
command file, DATATRIEVE aborts the entire procedure or command file if it 
executes an ABORT statement or you enter a CTRL/Z in response to a prompt. 

• When SET NO ABORT is in effect and DATATRIEVE is executing a procedure 
or command file, DATATRIEVE aborts only the statement containing the 
ABORT statement or prompt and executes the next statement in the procedure 
or command file. 

• With the SET COLUMNS_PAGE command, you can affect the output of a 
PRINT statement that contains no implicit line feeds, that is, no SKIP, no 
NEW_PAGE, or no COL n with n less than the column reserved for previous 
print list elements. 

If an element in a print list would extend beyond the right column limit deter- 
mined by the value of the COLUMNS-PAGE setting, DATATRIEVE shifts 
that element to the next line. By adjusting the COLUMNS-PAGE setting, you 
can control the way DATATRIEVE breaks the detail lines of its output. 

• If you use a partial file specification in the SET DICTIONARY command, 
DATATRIEVE uses your default dictionary to supply the missing part of the 
file specification. 

• If a SET DICTIONARY command fails because the specified dictionary file 
does not exist or because you do not have adequate privileges to it, your current 
dictionary does not change. 

• SET GUIDE on the VT100 family of terminals sets the scrolling attribute of 
your terminal to smooth scroll. When you leave Guide Mode, DATATRIEVE 
does not reset the scrolling attribute. 

Usage Note 

To display the name of your current dictionary, use the SHOW DICTIONARY 
command. 
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Example 

Set your current dictionary to NEWDIC.DIC, use a command to verify the 
change, return to your default dictionary with SET DICTIONARY, and verify 
the current dictionary. 

DTR> SET DICTIONARY NEWDIC(H) 
DTR > SHOW DICTIONARY© 

The current dictionary is DB2 : C 58 »23 3 NEWD I C . D I C i 1 
DTR> SET DICTIONARY© 
DTR > SHOW DICTIONARY© 

The current dictionary is LB : C 1 > 2 ] QUERY ♦ D I C 5 1 
DTR > 
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5.49 SHOW Command 

Function 

Displays information about your current data dictionary and its contents. 



Format 





ALL 






/ collection-name \ 






COLLECTIONS 






CURRENT 






\ DICTIONARY 






J DOMAINS 1 




SHOW 


v FIELDS [FOR domain-name] 
] object-name I 
f PROCEDURES \ 
' READY 

RECORDS 
\ SPACE J 

TABLES 


) [,..-] 



Arguments 

ALL 

Displays the names of all the objects catalogued in your current dictionary, 
the name of your current dictionary, the names of established collections, the 
readied domains, the loaded tables, and tables in your workspace. 

collection-name 

Displays the collection name, the name of the domain within which the collec- 
tion has been established, the number of records in the collection, the status 
of the selected record within the collection, and the names of the keys on 
which the collection has been sorted. 

COLLECTIONS 

Displays the names of the collections in your workspace. 

CURRENT 

Displays the name of the domain within which the CURRENT collection has 
been formed, the number of records in the CURRENT collection, the status of 
the selected record in the CURRENT collection, and the names of the keys on 
which the collection has been sorted. 

DICTIONARY 

Displays the full file specification of your current dictionary. 
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DOMAINS 

Displays the names of all domains cataloged in your current dictionary. 

FIELDS [FOR domain-name] 

Displays the names, data types, and index key information of the fields of all 
readied domains, or the domain specified in the FOR clause. The SHOW 
FIELDS command also displays the names and data types of global variables. 

object-name 

Displays the source text of a domain, record, procedure, or table definition 
specified by the object name. 

PROCEDURES 

Displays the names of all procedures cataloged in your current dictionary. 
READY 

Displays for each readied domain the file type of the associated data file, the 
access control option, and the access mode. 

RECORDS 

Displays the names of all record definitions cataloged in your current 
dictionary. 

SPACE 

Displays information on DATATRIE VE pool space and current memory 
usage. See the DATATRIEVE-11 User's Guide for information on using the 
SHOW SPACE command to optimize DATATRIEVE. 

TABLES 

Displays the names of all loaded tables and dictionary tables cataloged in 
your current dictionary. 

Restrictions 

• You must have R (read) access to a dictionary object before you can display it 
with the SHOW object-name command. 

• You can display objects only in your current dictionary, not in other dictionary 
files. 

Results 

• DATATRIEVE displays information, in the order requested, on your terminal. 

• You need only R (read) access to the objects in your current dictionary to see 
their names when you enter a SHOW command with one of these options: ALL, 
DOMAINS, RECORDS, PROCEDURES, TABLES, and DICTIONARY. 
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• If you do not have the access privileges needed to obtain information for the 
SHOW object-name command, DATATRIEVE displays an error message on 
your terminal and returns you to DATATRIEVE command level. 

• When you have more than one existing collection and you enter a SHOW 
COLLECTIONS command, the order in which DATATRIEVE displays the col- 
lections reverses the order in which you established them. The CURRENT col- 
lection is always at the top of the list, and the "oldest" existing collection is 
always at the bottom of the list. 

Knowing this order of the collections is useful because you can see the order in 
which DATATRIEVE searches for a selected record to establish a single record 
context for the MODIFY, PRINT, ERASE, and DISPLAY statements and 
resolve field names in value expressions. 

Examples 

Display the names of the objects in your current dictionary, 
db2:[56,34]NEWDIC.DIC: 

DTR> READY YACHTS® 
DTR> READY FAMILIES© 
DTR> READY AUTOMOBI LES(RFf) 
DTR> SHOW ALL© 
Domains: 

AUTOMOBILES Dl EDIT-TEST 

FAMILIES OWNERS PERSONNEL 

Records: 

AUTOMOBILES_REC D1REC ED I T_REC 

FAMILY _REC OWNER-REC PART-REC 

YACHT 
Procedures: 

A F00 F001 

NUM1 NUM2 SELL-BOAT 

Tables: 

The current dictionary is DBA2 : CSS >34]NEWDIC«DIC51 
No established collections 
Read y d o k a i n s : 

YACHTS: RMS INDEXED > PROTECTED READ 

PERSONNEL: RMS SEQUENTIAL > PROTECTED READ 

DTR> 



Display the record definition OWNER-RECORD: 

DTR> SHOW OWNER-RECORD© 
RECORD OWNER-RECORD 
01 OWNER ♦ 

03 NAME PIC XUO) QUERY - HEADER IS "OWNER "/ "NAME " 

EDIT-STRING IS X(5> ♦ 
03 BOAT-NAME PIC XU7) QUERY-HEADER IS "BOAT NAME 
03 TYPE. 

OS BUILDER PIC X( 10) ♦ 

OS MODEL PIC X( 10) , 

5 

DTR > 



EMP-REYIEW 
YACHTS 

EMP_REV_REC 

PERSONNEL-REC 



IFl 
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5.50 SHOWP Command 

Function 

Displays the access control list (ACL) of an object in your current dictionary on 
your terminal: 

Format 



SHOWP object-name 




Arguments 

object-name 

Is the name of the dictionary object whose ACL you want to display on your 
terminal. 

(passwd) 
(*) 

Is the password necessary to gain C (control) access to the domain. The paren- 
theses are required. Use the asterisk to have DATATRIEVE prompt for the 
password. If you omit this argument, DATATRIEVE uses your UIC/PPN to 
verify that you have C (control) access privilege. 

Restriction 

You must have C (control) access privilege to the object before you can display its 
ACL. 

Result 

DATATRIEVE displays the entire ACL for the specified dictionary object on your 
terminal. 

Usage Notes 

• Use the SHOWP command to verify the sequence number of the entry you 
want to delete before you use the DELETEP command to remove the entry 
from an access control list. 

• Refer to the DATATRIEVE-1 1 User's Guide for information on protection and 
access control lists. 
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Examples 

Display the access control list for the YACHTS domain: 

DTR > SHOWP YACHTS© 

1 »UIC f [32 ,5G] * "RWMEC " 

DTR > 

Use a password (CEP) to gain C (CONTROL) access to the record YACHT and 
display its access control list: 

DTR > SHOWP YACHT (*)© 

Enter password for YACHT: © 

DTR > SHOWP YACHT© 

1 »UIC * [23 ,451 t "RWMEC " 

2 >UIC , [34 ,S4] * "RW" 

DTR > 
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5.51 SIGN Clause 

Function 

Specifies the location and representation of a sign ( + or -) in a numeric elemen- 
tary field in a record definition. 

Format 



SIGN [IS] | TRAILING } [SEPARATE] 



Arguments 

LEADING 
TRAILING 

Indicates that the sign is at the left (LEADING) or right (TRAILING) of the 
field value. 

SEPARATE 

Indicates that the sign occupies its own character position in the field. If this 
argument is omitted, the sign shares a character position with the field's left- 
most (if LEADING) or rightmost (if TRAILING) digit. 

Restrictions 

• This clause can be used only with numeric elementary fields. 

• A field definition cannot contain both a SIGN and a USAGE clause. 
Results 

• If you do not include a SIGN clause with a numeric field, the sign shares a 
character position with the field's rightmost digit. You must include this clause 
if a program written in COBOL (or other language) uses the record and 
requires that the sign be a separate character or share the leftmost character 
position: 

• A sign clause does not affect the output format of a field. 
Examples 

Define the field CURRENT_BALANCE as a six-digit signed field, with the sign 
sharing the leftmost character position: 

03 CURRENT-BALANCE 

PIC IS S9999V99 

ED I T_STR I NG IS $$$$9.99- 

SIGN IS LEADING, 
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Define the field NEW_ PRICE as a four-digit signed field. The sign is a separate 
character in the rightmost character position. 

03 NEW-PRICE PIC S99V99 

SIGN TRAILING SEPARATE 
EDIT_STRING +++.a9. 



5-212 Commands, Statements, and Definition Clauses 



SORT 



5.52 SORT Statement 

Function 

Arranges a DATATRIEVE collection according to the order you specify for the 
contents of one or more fields in the records. 

Format 

SORT [collection-name] [BY] sort-key-1 [,...] 

Arguments 

collection-name 

Is the name of the collection to be sorted. 

BY 

Is an optional language element you can use to clarify syntax, 
sort-key 

Is a field to be used for the sort. If you specify more than one sort key, use a 
comma to separate each sort key from the next. The sort key can be preceded 
or followed by a key word that determines the order in which DATATRIEVE 
sorts the records in the collection: 

ASC [ENDING] 
DESCENDING] 
INCREASING 
DECREASING 

ASCENDING is the default order. 

Restrictions 

• You can use the SORT statement only to sort a collection already formed with 
a FIND statement. 

• Do not use a FIND and a SORT statement in the same compound statement. 

• Do not use a SORT statement in a FOR, WHILE, or REPEAT statement. 
Results 

• If you omit the collection name, DATATRIEVE sorts the current collection. 

• If you specify ASC[ENDING] or INCREASING in the sort key, DATATRIEVE 
puts the record with the lowest value in the specified field first in the collection 
and the one with the highest value last. 
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• If you specify DESCENDING] or DECREASING, DATATRIEVE puts the 
record with the highest value in the specified field first in the collection and the 
one with the lowest value last. 

• DATATRIEVE sorts the collection according to the order and fields specified: 

- If you specify more than one sort key, DATATRIEVE uses the first field 
name as the major sort key and each successive field name as an increas- 
ingly minor key. 

- If, in the first sort key, you omit a key word specifying the sort order, 
DATATRIEVE sorts the collection according to the ascending order of the 
contents of that field. 

- If, in the second or subsequent sort keys, you omit a key word specifying the 
sort order, DATATRIEVE uses the sort order implied or specified for the pre- 
ceding sort key. 

• When DATATRIEVE executes the SORT statement, any selected record in the 
collection is released, and the collection cursor does not point to any record in 
the collection. 

Usage Notes 

• You can specify any number of sort keys. 

• To sort record streams, use the SORTED BY clause of the record selection 
expression that creates the record stream. 

• To sort collections as you form them, use the SORTED BY clause of the RSE in 
the FIND statement. 

Example 

Form a collection of the yachts built by Grampian, sort the collection by descend- 
ing length over all, and then print the collection: 

DTR> SET NO PROMPT© 
DTR> READY YACHTS© 

DTR> FIND YACHTS WITH BUILDER = "GRAMPIAN"© 
Z 5 records found] 

DTR> SORT CURRENT BY DESC LOA© 
DTR > PRINT CURRENT© 









LENGTH 












U E R 






ANUFACTURER 


MODEL 


RIG 


ALL 


WEIGHT 


BEAM PRICE 


GRAMPIAN 


2-34 


SLOOP 


34 


1 1 ,800 


10 $29,875 


GRAMPIAN 


34 


KETCH 


33 


12 ,000 


10 $29,875 


GRAMPIAN 


30 


SLOOP 


30 


8 ,800 


08 $17,775 


GRAMPIAN 


28 


SLOOP 


28 


8 ,300 


10 $14,475 


GRAMPIAN 


2G 


SLOOP 


26 


5 ,800 


08 $11 ,495 



DTR > 
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5.53 STORE Statement 

Function 

Creates a record in a DATATRIEVE domain and stores values in one or more 
fields of the record. 

Format 

STORE [context-variable IN] domain-name 
[USING statement-1] 
[VERIFY [USING] statement-2] 



Arguments 

domain-name 

Is the given name or alias of the domain to contain the new record. You can 
prefix a context variable to the domain name by using this format: 

[context-variable IN] domain-name 

See the DA TA TRIEVE-1 1 User's Guide and Chapter 3 of this manual for 
information on context variables. 

USING statement-1 

Specifies a DATATRIEVE statement that prompts for or contains values for 
one or more fields in the new record. 

VERIFY [USING] statement-2 

Specifies a statement DATATRIEVE executes just before storing the new 
record. 

Restrictions 

• The domain specified in the STORE statement must be readied for write or 
extend access before you can store records in it. 

• You cannot store a new record in an RMS relative file or a view. 

• You cannot store values in the fields of a list with the USING clause. To store 
values in list fields, omit the USING clause and DATATRIEVE will prompt 
you for a value for each field in the record. You can also make no reference to 
the list fields in the USING clause, and use the MODIFY statement later to 
enter values in the list fields. 



Commands, Statements, and Definition Clauses 5-215 



STORE 

Continued 



• If you include the keyword USING when specifying statement 1, you must put 
USING on the same input line as the domain name, unless you end the input 
line with a continuation character (-). If you omit the keyword USING and the 
continuation character, you must put at least the first element of statement 1 
on the same input line as the domain name. 

• Unless you end your input line with the continuation character (— ), do not 
press the RETURN key immediately before typing the keyword VERIFY. 

• You cannot store a new record in an RMS indexed file if field values of the 
record duplicate values in either a primary or alternate key field with the NO 
DUP attribute. 

• You cannot store a value in a COMPUTED BY field. 

• To use the name of a REDEFINES field when storing a record, you must 
specify the name in a USING clause. Otherwise, DATATRIEVE prompts you 
with the name of the elementary field from which the REDEFINES field takes 
its value. 

Results 

• If you omit the USING statement 1 clause, DATATRIEVE prompts you for a 
value for the first elementary field in the record with this message: 

ENTER field-name: 

After you enter a value, DATATRIEVE prompts for a value for the next ele- 
mentary field in the record, and so on, until you have entered a value for every 
elementary field in the record. 

• After you supply a value to the last elementary field in the record, 
DATATRIEVE adds the record to the data file. 

• If you press only RETURN in response to a prompt, DATATRIEVE repeats the 
prompt. 

• To enter all spaces in an alphabetic or alphanumeric field or to enter all zeros 
in a numeric field, respond to the STORE statement's prompt with one or more 
spaces and press RETURN. 

• If you enter two or more TABs to a prompt for an alphanumeric field, 
DATATRIEVE stores the TAB characters in the field. If you enter two or more 
TABs to a prompt for a numeric field, DATATRIEVE displays an error mes- 
sage on your terminal and prompts you again for valid numeric data. 

• If you type CTRL/Z in response to any prompt for a field value, DATATRIEVE 
aborts the STORE statement and returns you to DATATRIEVE command 
level. No new record is stored. 
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• If you enter more characters or digits than the field definition specifies in 
response to a prompt, DATATRIEVE displays an error message and reprompts 
for the value. 

• If you enter data that conflicts with the conditions specified by a VALID IF 
clause in the record definition, DATATRIEVE reprompts for valid data. 

• If you specify a VERIFY USING clause, no data is stored until DATATRIEVE 
successfully executes statement 2. If the VERIFY USING clause contains an 
ABORT statement in an IF-THEN-ELSE statement and the abort conditions 
are met, DATATRIEVE aborts the STORE statement without storing the 
record and returns you to DATATRIEVE command level. This abort occurs 
whether you have SET ABORT or SET NO ABORT in effect. 

Usage Notes 

• Use the following two forms of the assignment statement in the USING 
statement- 1 clause: 

field-name = value-expression 

group-field-name-1 = group-field-name-2 

• Each time DATATRIEVE completes the execution of a STORE statement, the 
new record is stored in the data file. If a STORE statement in a loop creates a 
record each time DATATRIEVE executes the loop, DATATRIEVE stores each 
new record in the data file when it executes the STORE statement. If you abort 
the loop with a CTRL/Z, CTRL/C, or ABORT statement, records already stored 
in the data file are not affected. 

• You must use either the ERASE statement (for indexed files) or the MODIFY 
statement (for sequential files) to remove records from data files once the 
STORE statement has executed. 

• To store more than one record in a domain, use a REPEAT statement: 
REPEAT n STORE domain-name 

The argument n specifies the number of records to be stored. You can avoid 
counting the new records you want to store by making n larger than the esti- 
mated number of new records. When you finish storing records, stop the 
prompts for data by typing CTRL/Z in response to the prompt. DATATRIEVE 
then returns you to command level. 
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• You can use the VERIFY clause to check the validity of data before 
DATATRIEVE stores a new record by putting an ABORT statement in an 
IF-THEN-ELSE statement that establishes conditions for the abort: 

- DATATRIEVE first checks the value you supply to a STORE or MODIFY 
statement prompt against any validation conditions specified for that field in 
the record definition. If the value passes this validation test, it is then 
checked against the conditions in the VERIFY clause of the STORE or 
MODIFY statement. 

— If you always use the same validation conditions for modifying and storing 
data, put those conditions in VALID IF clauses in the record definition. That 
way, DATATRIEVE reprompts you for another value for the same field if 
the value you entered does not pass the validation test. When you use an 
ABORT statement in the VERIFY clause to validate a value, 
DATATRIEVE returns you to DATATRIEVE command level if the value 
does not pass the validation test and you must reenter the STORE or 
MODIFY statement. 

• You can also put a BEGIN-END block containing a series of IF-THEN-ELSE 
statements in the VERIFY clause to explicitly control the storing of records. 

• You can transfer information from one domain to another with the STORE 
statement by using the following syntax to nest the STORE statement in a 
FOR loop: 

FOR domain-1 

STORE domain-2 USING 

group-field-name-2 = group-field-name-1 

The group fields do not have to contain identical elementary fields, but 
DATATRIEVE transfers values only between elementary fields with identical 
field names. Use this method when a record contains duplicate elementary 
field names subordinate to different group fields. 

Use this method to transfer data between RMS sequential files and RMS 
indexed files. Both domains can share the same record definition, but the defi- 
nition of one domain specifies a sequential file, and the other an indexed file. 
See the DEFINE FILE command for details on specifying types of file organiza- 
tion. 

• You can also transfer elementary field values from one domain to another. Put 
a STORE statement in a FOR statement whose rse selected the desired source 
records, then put the necessary assignment statements in the USING clause of 
the STORE statement. 

• Take special care when storing data in primary key fields of RMS indexed files 
and in other fields with the NO CHANGE attribute. Values in these fields can- 
not be changed with the MODIFY command, and errors can only be corrected 
by creating a new record with the correct value and erasing the old record. 
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• Use a context variable with the domain name in the STORE statement if you 
want to refer to the values you have entered before D ATATRIE VE stores the 
record. By using context variables, you can use the values for VERIFY USING 
clauses as in the second example, or you can use the values of one field to calcu- 
late the values of other fields to be stored in the record. The following example 
calculates and stores a yearly total after storing the quarterly quantities: 

DTR> SET NO PROMPT© 

DTR> STORE X IN ACCOUNTS USING© 

CON> BEGIN©) 

CON> 01 = *.01© 

C0N> 02 = *.02© 

C0N> 03 = *.03© 

C0N> 04 = *,04© 

C0N> FY = X.01 + X.02 + X.03 + X, 04(H) 

C0N> END© 
Enter 01: 



Examples 

Store two records in the FAMILIES domain: 



DTR> SET NO PROMPT© 

DTR> READY FAMILIES WRITE© 

DTR> REPEAT 2 STORE FAMILIES© 

Enter FATHER: RUSSELL© 

Enter MOTHER: KAREN© 

Enter NUMBER_K I DS : 2© 

Enter K I D_N AME : JENNIFER© 

Enter AGE: 12© 

Enter K I D_NAME : LESLIE© 

Enter AGE: 3® 

Enter FATHER: WAYNE© 

Enter MOTHER: SHEEL© 

Enter NUMBER-K I DS : 2© 

Enter K I D_NAME : BETE© 

Enter AGE: 8© 

Enter K I D_N AME : ALEX© 

Enter AGE: 5© 

DTR> FIND FAMILIES WITH MOTHER 
C 2 records found] 
DTR> PRINT ALL© 



"KAREN" > "SHEEL 1 



FATHER 
RUSSELL 
WAYNE 



MOTHER 
KAREN 
SHEEL 



NUMBER 
KIDS 



KID 
NAME 

JENNIFER 
LESLIE 
BETE 
ALEX 



AGE 

12 
9 
8 
5 



DTR > 
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Store a record in the YACHTS domain, using a context variable and a VERIFY 
clause: 

DTR> SHOW HINKLEY-STORE© 
PROCEDURE HINKLEY -STORE 
STORE A IN YACHTS USING 
BEGIN 

BUILDER = "HINKLEY" 

MODEL = "BERMUDA 40" 

RIG = "YAWL" 

LO A = 40 

D I S P = 200 

BEAM = 12 

PRICE = 8200 
END VERIFY USING 
BEGIN 

PRINT A ♦ BOAT » SKIP 

IF *♦ CONFIRMATION CONT "N" THEN 

PRINT SKIP THEN ABORT "Bad record" 

END 

END-PROCEDURE 



DTR> READY YACHTS WRITE® 
DTR> : HINKLEY-STORE© 



MANUFACTURER MODEL RIG 
HINKLEY BERMUDA 40 YAWL 

Enter CONFIRMATION: N© 



LENGTH 
OVER 

ALL WEIGHT BEAM 



40 



20 »00 



12 



PRICE 
$82 »000 



ABORT: Bad record 

Execution terminated by "ABORT" statement 
DTR> 

Define a domain for single-digit integers and their squares, and use a WHILE 
statement to control the number of records stored in the domain: 



DTR> 
DTR > 
DFN> 
DTR > 
D F N > 
D F N > 
DFN > 
DFN> 
[Rec 
DTR > 
DTR > 
DTR > 
DTR > 
DTR > 
DTR > 
CON> 
CON> 
CON> 
CON> 
CON> 
DTR > 
CIO 
DTR > 



SET NO PROMPT© 

DEFINE DOMAIN SQUARES USING© 
SQUARES_REC ON SQUARES ♦ DAT ! (ret) 
DEFINE RECORD SQUARES-REC USING© 
01 SQUARES,© 

03 NUMBER PIC 9.© 

03 ITS-SQUARE PIC 99*© 

>© 

o r d is 3 bytes lons«] 
DEFINE FILE FOR SQUARES 5© 
READY SQUARES WRITE© 
DECLARE N PIC 99,© 
N = 0© 
REPEAT 10© 
STORE SQUARES USING© 
BEGIN© 



N * N© 



NUMBER = 
ITS-SQUARE 
N = N + 1© 
END© 

FIND SQUARES© 
records found] 

PRINT ALL© 



(continued on next page) 
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ITS 

NUMBER SQUARE 









1 


01 




04 


3 


09 


a 


IB 


5 


25 


6 


3B 


7 


49 


8 


G4 


9 


81 



DTR> 



Store data from the WORKER domain into an expanded domain, 
NEW_WORKER. These domains have duplicate elementary field names that 
are subordinate to different group field names. Use a FOR statement to nest the 
STORE statement so that DATATRIE VE stores the data from the elementary 
fields correctly. Here are the record definitions and the STORE statement: 



DTR> SET NO PROMPT© 
DTR> SHOW WORK-REC© 
RECORD WORK-REC 

USING 
01 WORK . 

03 LOCAL ♦ 

05 CITY PIC 
05 STATE PIC 
03 REMOTE ♦ 

05 CITY PIC 
05 STATE PIC 



X (10) 
X < 2 ) . 

X (10) 
X < 2 ) • 



DTR> SHOW NEW_WORK_REC© 
RECORD NEW-WORK-REC 

USING 
01 WORK ♦ 

03 NEW-LOCAL, 

05 CITY PIC X( 10) , 
05 STATE PIC X(2) , 
03 NEW-REMOTE, 

05 CITY PIC X( 10) , 
05 STATE PIC X(2) ♦ 
03 NAME ♦ 

05 FIRST PIC X( 10) ♦ 
05 LAST PIC X( 15) ♦ 



DTR > READY WORKER© 

DTR > READY NEW-WORKER WRITE© 

DTR > FOR WORKER© 

C0N> STORE NEW-WORKER USING© 

C0N> BEGIN© 

C0N> NEW-LOCAL = LOCAL© 

C0N> NEW-REMOTE = REMOTE© 

DTR END© 
DTR > PRINT WORKER© 



(continued on next page) 
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CITY STATE C I T> 
NASHUA NH BOSTON 

D T R > PRINT NEW_WORKER(reT) 

CITY STATE C I "H 



NASHUA 
NASHUA 



NH BOSTON 
NH BOSTON 



STATE 
MA 

STATE 

MA 
MA 



FIRST 



LAST 



DTR > 



5-222 Commands, Statements, and Definition Clauses 



SUM 



5.54 SUM Statement 

Function 

Provides a summary of totals for one or more numeric fields in the current collec- 
tion. The summary is sorted according to the values in one or more fields of the 
current collection. The summary includes subtotals for control groups and can be 
written to a file or an output device. 



Format 




Arguments 

print-list 

Is a list of one or more numeric fields, other value expressions, and modifiers. 
The format of the print list is: 

{value-expression [{modifier} [...]]} [,...] 

sort-list 

Is a list of one or more sort keys that determine the order in which 
DATATRIEVE presents the summary totals. An item in the sort list consists 
of the name of a field to be used for the sort, preceded or followed by a key 
word that determines the order in which DATATRIEVE sorts the records in 
the collection: 

ASC [ENDING] 
DESCENDING] 
INCREASING 
DECREASING 

ASCENDING is the default order. If you specify more than one sort key, use a 
comma to separate each sort key from the next. 

file-spec 

Is the file to which you want to write the output of the statement. The file spe- 
cification must have this format: 

For RSTS/E systems: dev:[PPN]file-name.type 

For RSX systems: dev:[UIC]file-name.type;ver 
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You must specify at least one field in the file specification. On RSTS/E sys- 
tems, you must specify a file name. DATATRIEVE uses the following defaults 
for fields not specified: 



Field Default 

dev: SY: (the system device) 

[UIC/PPN] Your default UIC/PPN 

file name No default 

.type .LST 

;ver 1 or next higher version 

(non-RSTS/E systems only) 

.prompt-name 



Is a prompting value expression that prompts for the specification of the file to 
which you want to write the output of the statement. 

Restrictions 

• You must have established a current collection before you can use the SUM 
statement. 

• You cannot use the SUM statement with COMPUTED BY fields. 

• You must include only numeric fields in the print list. 
Results 

• DATATRIEVE creates a record stream based on the current collection, sorts 
the records of the record stream according to the specifications in the sort list, 
and displays the summary on your terminal or writes it to the file specified in 
the ON clause. 

• The summary consists of totals for the fields specified in the print list. For each 
control group created by the sort list, there is a total for each field in the print 
list. At the end of the summary is a total for each value expression in the print 
list of the values for all the records in the record stream. 

• The order and format of the data in the report depends on the arguments you 
select. 

• If you omit the ON clause, DATATRIEVE displays the output on your 
terminal. 

Usage Note 

Use edit strings to format the output of the totals for items in the print list. 
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Example 



Form a collection of yachts. Use the SUM statement to summarize the prices of 
yachts in the collection and to display the number of yachts built by each builder. 
Use edit strings to format the values: 

DTR> SHOW SUM-YACHTS© 
PROCEDURE SUM_YACHTS 



READY YACHTS 

FIND FIRST 6 YACHTS 

SUM 1 ( "NUMBER" /"OF YACHTS") USING S» 
PRICE USING $$$$,$$$ BY BUILDER 



END-PROCEDURE 
DTR> : SUM_YACHTS© 



MANUFACTURER OF 



NUMBER 
F YACHTS 



PRICE 



NUMBER 
OF YACHTS 



PRICE 



ALBERG 
ALB I N 
AMERICAN 



3 



$3S ,351 
$64 » 000 
$28 »790 



S 



$129 ,741 



D T R > 



Commands, Statements, and Definition Clauses 5-225 



THEN 



5.55 THEN Statement 

Function 

Joins two or more DATATRIEVE statements into a compound statement. 
Format 

statement-1 {THEN statement-2} [...] 



Argument 

statement 

Is a DATATRIEVE statement. 
Restrictions 

• You must observe all restrictions on the statements included in the compound 
statement. Restrictions are listed in the descriptions of each statement. 

• You cannot use DATATRIEVE commands in a compound statement. 

• A procedure invoked in a compound statement cannot contain DATATRIEVE 
commands. 

• Do not include FIND and SELECT in the same compound statement. 

• Do not include FIND and SORT in the same compound statement. 

• Do not include SELECT and DROP in the same compound statement. 
Results 

• DATATRIEVE executes statements in compound THEN statement in the 
order entered. 

• If any statement in a compound THEN statement contains a syntax error, 
DATATRIEVE does not execute any of the statements in the THEN statement. 

Usage Notes 

• You can use a compound statement anywhere you can use a single statement. 

• Use THEN statements rather than BEGIN-END blocks to form short com- 
pound statements. 

• If you use any statement that creates a context in the compound statement, do 
not use any other statement in that compound that refers to or depends on that 
context information. 
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THEN 

Continued 



Example 

Use THEN to join a PRINT statement and a MODIFY statement in a FOR loop: 

DTR > SET NO PROMPT© 

DTR > READY YACHTS MODIFY© 

DTR > FOR YACHTS WITH BUILDER EO "ALBUM"© 
CON> PRINT THEN MODIFY© 

LENGTH 
OYER 

MANUFACTURER MODEL RIG ALL WEIGHT BEAM PRICE 

ALB I N 79 SLOOP 26 4 >200 10 $17 #900 

Enter MANUFACTURER : Z 
Execution terminated by operator 

DTR> 
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5.56 USAGE Clause 

Function 

Specifies the internal format of a numeric field or specifies a date field. 
Format 

/ DISPLAY 

(COMP ) 
{INTEGER | 

\ (COMP-1 ) 
] I REAL J 

[USAGE [IS]] / f COMP-2 ) 
\ ( DOUBLE J 

/ (COMP-3 ) 
/ (PACKED J 

I (COMP-5 ) 
I (ZONED J 

\ DATE 



Arguments 

DISPLAY 

Indicates that each digit occupies one byte of storage. DISPLAY is the default 
if you do not include a USAGE clause. 

COMPINTEGER 

Indicates that the field value is stored in binary format. INTEGER is a syn- 
onym for COMP. 

COMP-1 REAL 

Indicates that the field value is stored in single-precision real format. REAL 
is a synonym for COMP-1. 

COMP-2 DOUBLE 

Indicates that the field value is stored in double-precision real format. 
DOUBLE is a synonym for COMP-2. 

COMP-3 PACKED 

Indicates that the field value is stored in packed decimal format. PACKED is 
a synonym for COMP-3 . 



5-228 Commands, Statements, and Definition Clauses 



USAGE 
Continued 



COMP-5 ZONED 

Indicates that the field value is stored in signed decimal format. ZONED is a 
synonym for COMP-5. 

DATE 

Indicates that the field is a date field. 
Restrictions 

• This clause is valid only for elementary numeric or date fields. 

• A field definition cannot contain both a USAGE clause and a SIGN clause. 
Results 

• The USAGE clause determines the internal storage format of a numeric field. 
If a numeric field definition does not have a USAGE clause, each digit in the 
field value occupies one character position in the record. 

• The USAGE IS DATE clause identifies the field as a DATATRIEVE date field. 
Usage Notes 

• Use the appropriate form of the USAGE clause when a program written in 
COBOL, BASIC-PLUS-2, or other language uses the record and requires a dif- 
ferent internal format. 

• The USAGE clause can cause DATATRIEVE to align fields on hardware stor- 
age boundaries. See the section in this chapter on the ALLOCATION clause for 
information on word boundary alignment. 

• A COMP (or INTEGER) field stores values in binary format. The size of a 
COMP (or INTEGER) field depends on the number of digit positions specified 
in its PICTURE clause. 

• A COMP-1 (or REAL) field stores values in single-precision real (floating 
point) format. COMP-1 fields are four bytes long. 

• A COMP-2 (or DOUBLE) field stores values in double-precision real (floating 
point) format. COMP-2 fields are eight bytes long. 

• A COMP-3 (or PACKED) field stores values in packed decimal format, two dig- 
its per byte. The value of a COMP-3 field must contain a sign. The sign occu- 
pies the four low-order bits in the rightmost byte. The size of the field depends 
on the number of digit positions specified by the field's PICTURE clause: 

digit-positions + 1 

size (in bytes) = 

2 

For example, a field with three digit positions is two bytes long. If the field con- 
tains an even number of digits, the size is rounded up. Thus, a six-digit field is 
stored in four bytes. 
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• A COMP-5 (or ZONED) field stores values in signed decimal format, one digit 
per byte. Therefore, the size of a COMP-5 field is the number of digit positions 
specified in its PICTURE clause. 

The sign of a COMP-5 value shares the rightmost byte with the lowest- valued 
digit of the value. The lowercase letters p through y represent a negative sign 
for the values through & 

• A DATATRIEVE date field stores a date as an eight-byte binary value. Other 
languages will not interpret the date field correctly. The date is expressed as 
the number of 100-nanosecond units (clunks) since the base date of 00:00:00 
AM on November 17, 1858. 

When you enter a date value, DATATRIEVE translates the input value to 
clunks before storing it. When you print a date field, DATATRIEVE translates 
the number of clunks to the format specified in the EDIT_STRING clause, or to 
the default format if no EDIT_ STRING clause is included in the field defini- 
tion. The default format is DD-MMM- YYYY. 

• Use the DATATRIEVE date value expression, "TODAY", to assign the current 
system date to a DATE variable or field. For example: 

DTR> DECLARE X USAGE DATE ♦ (RET) 
DTR> X = "TODAY "(ret) 
DTR> PRINT )«m 

X 

1 i-Feb-83 
DTR> 

Examples 

Define the field SALE_DATE as a date field, to be printed in the default format 
for date fields: 

OB SALE-DATE USAGE IS DATE* 

Define the field SALE-PRICE as a COMP-1 (REAL) field: 

05 SALE-PRICE PIC 9(5) 
USAGE REAL 
EDIT-STRING IS $(B) ♦ 
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5.57 VALID IF Clause 

Function 

Validates a value for the field before it is stored in the record. 
Format 

VALID IF boolean-expression 



Arguments 

boolean-expression 

Is a DATATRIEVE Boolean expression. 

Restriction 

A field definition cannot contain both a VALID IF and a COMPUTED BY clause. 
Result 

When you enter a value for the field in response to a MODIFY or STORE state- 
ment prompt, DATATRIEVE evaluates the Boolean expression. If the Boolean 
expression is true, DATATRIEVE stores the value in the field. If it is false, 
DATATRIEVE prints an error message and reprompts for the field value. 
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Example 

The YACHT record contains VALID IF clauses for the RIG, LOA, and PRICE 
fields. DATATRIEVE stores only RIG values of SLOOP, KETCH, MS, and 
YAWL, LOA values between 15 and 50, and PRICE values greater than 1.3 
times the displacement or equal to zero: 

DTR > SHOW YACHT© 
RECORD YACHT 
USING 

ALLOCATION IS LEFT-RIGHT 
01 BOAT. 
03 TYPE. 

OS MANUFACTURER PIC X(10) 

QUERY-NAME IS BUILDER. 
OB MODEL PIC X( 10) . 
03 SPECIFICATIONS 

QUERY-NAME SPECS. 
OS RIG PIC X(G) 

VALID IF RIG EQ " SLOOP " » " K ETCH "t" MS " » " YAWL " . 
OS LENGTH-OVER- ALL PIC XXX 

VALID IF LOA BETWEEN 15 AND 50 

QUERY-NAME IS LOA. 
OS DISPLACEMENT PIC 99399 

QUERY-HEADER IS "WEIGHT" 

EDIT-STRING IS ZZ >ZZ9 

QUERY-NAME IS DISP. 
OS BEAM PIC 99. 
OB PRICE PIC 99999 

VALID IF PRICE>DISP*1 .3 OR PRICE EQ 

EDIT-STRING IS $$$»$$$. 

5 

DTR > READY YACHTS MODIFY© 

DTR> FIND FIRST 1 YACHTS WITH BUILDER = " ALB I N "(ret) 
CI Record found] 
DTR > SELECT© 

DTR> MODIFY RIG, LOA , PRICE© 

Enter RIG: CANOE© 

Validation error for RIG 

Re-enter RIG: SLOOP© 

Enter LENGTH_OVER_ALL : G2© 

Validation error for LENGTH_OVER_ALL 

Re-enter LENGTH_OVER_ALL : 45© 

Enter PRICE: 4200© 

Validation error for PRICE 

Re-enter PRICE: "Z 

Execution terminated by operator 

DTR> 
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5.58 WHILE Statement 

Function 

Causes DATATRIE VE to repeat a statement as long as the condition specified in 
the Boolean expression is true. 

Format 

WHILE boolean-expression statement 

Arguments 

boolean-expression 

Is a Boolean expression. Boolean expressions in the WHILE statement are 
limited to this format: 

variable-name boolean-operator value-expression 

*. prompt 

statement 

Is a simple or compound statement you want D ATATRIE VE to execute if the 
Boolean expression evaluates to true. 

Restrictions 

• You must observe all restrictions for statements in the WHILE statement. 

• You cannot use a field name as a value expression on the left side of the 
Boolean expression of a WHILE statement. 

Result 

DATATRIE VE repeats the specified statement as long as the Boolean example 
evaluates to true. If the relationship between the two values in the Boolean 
expression never changes (1 = 1, for example), the loop repeats infinitely until 
you end it with a CTRL/C or CTRL/Z. 

Usage Notes 

• Use the WHILE statement to form and control the execution of loops. 

• You can use a prompting value expression or a variable as the first member of 
the Boolean expression. 
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Example 

Group the boats with LOA less than 35 according to the value of BEAM. Display 
the TYPE, LOA, and BEAM of the shortest boat from each group of boats with 
the same value for BEAM: 

DTR> READY YACHTS© 
DTR> SHOW WHILE_EX© 
PROCEDURE WHILE _EX 
BEGIN 

DECLARE X PIC 99, 
X = 

FOR YACHTS WITH LOA < 35 AND 

BEAM NE SORTED BY BEAM * LOA 

WHILE X < BEAM 

BEGIN 

PRINT TYPE* LOA, BEAM t X 
X = BEAM 

END 

EJMD 

ENO_ PROCEDURE 
DTR> 2 WHILE -EX© 

LENGTH 







OVER 






MANUFACTURER 


MODEL 


ALL 


BEAM 


X 


CAPE DORY 


TYPHOON 


19 


OS 


00 


WINDPQWER 


IMPULSE 


IB 


07 


OB 


ERIC SON 


23/ SPECIA 


23 


OS 


07 


EASTWARD 


HO 


24 


09 


OS 


ALB IN 


79 


26 


10 


09 


BOMBAY 


CLIPPER 


31 


1 1 


10 


IRWIN 


25 


25 


12 


1 1 



DTR > 



5-234 Commands, Statements, and Definition Clauses 



DATATRIEVE-1 1 Keywords 



a n /~\ T"» m 

ABORT 


ADT 


ADVANCED 


A T T/~*1 XTT71TV Hi* T /~~\ T~\ A TTXT/^vTl 

ALIGNED_MAJOR_MINOR 


ALL 


ATT A mT/"\"\T 

ALLOCATION 


AND 


ANY 


A Ct 

AS 


ASC 


ASCENDING 


AT 


AVERAGE 


T"> T71 /""I TTVT 

BEGIN 


T"> T7> m"\T TT71 T7* 1VT 

BETWEEN 


BOTTOM 


BT 


BUT 


BY 


CHANGE 


nTT a n A /"imTTin 

CHARACTER 


CHARACTERS 


CLOSE 


COL 


COLLECTIONS 


COLUMN 


C OLUMN S _ PAGE 


COLUMN-HEADER 


COMP 


COMPUTED 


C0MP_1 


COMP_2 


COMP_3 


C0MP_5 


COMP- 6 


CONNECT 


CONT 


CONTAINING 


COUNT 


DATATYPE 


DATE 


DECIMAL 


DECLARE 


DECREASING 


DEFINE 


DEFINEP 


DELETE 


DELETEP 


DEPENDING 


DESC 


DESCENDING 


DICTIONARY 


DIGIT 


DIGITS 


DISPLAY 


DOMAIN 


DOMAINS 


DOUBLE 


DROP 


DUP 


D_ FLOATING 


EDIT 


EDIT_ STRING 


ELSE 


END 


END-PROCEDURE 


END_ REPORT 


END_TABLE 


EQ 


EQUAL 


ERASE 


EXCLUSIVE 


EXIT 


EXTEND 


EXTRACT 


FIELDS 


FILE 


FILL 


FIND 


FINISH 


FIRST 


FN1 


FN2 


FN3 


FOR 


FORM 


FROM 


F.FLOATING 


GE 


GREATER-EQUAL 


GREATER_THAN 


GT 


GUIDE 


HELP 


IF 


IN 


INCREASING 


INTEGER 


IS 


KEY 


LAST 


LE 


LEADING 


LEFT 


LEFT-RIGHT 


LESS_EQUAL 


LESS-THAN 


LINES-PAGE 


LONGWORD 


LT 


MAJOR-MINOR 



A-1 



MATCH 

MAX_PAGES 

MIN 

NEW-PAGE 
NO 

NO_ DATE 
NUMERIC 
ON 

OVERPUNCHED 

PAGE 

PLOT 

PROCEDURE 

PROTECTED 

QUERY_ HEADER 

READY 

RECORDS 

REPEAT 

REPORT- NAME 

SELECT 

SETS 

SHOWP 

SIZE 

SORTED 

STRING 

SUM 

SYNC 

TABLES 

THEN 

TOP 

UIC 

USING 

VERIFY 

WITH 

WRITE 



MAX 
MEDIAN 
MODIFY 
NEW_ SECTION 
NOT 

NO_NUMBER 

OCCURS 

OPEN 

OWNER 

PIC 

PORT 

PROCEDURES 
PW 

QUERY. NAME 
REAL 

REDEFINES 

REPORT 

RIGHT 

SEPARATE 

SHARED 

SIGN 

SKIP 

SPACE 

STRUCTURE 

SUPERCEDE 

TAB 

TEXT 

TIMES 

TOTAL 

UNSIGNED 

VALID 

VIA 

WITHIN 
ZONED 



MAX_ LINES 
MEMBERS 
NE 
NEXT 

NOT-EQUAL 

NUMBER 

OF 

OR 

PACKED 

PICTURE 

PRINT 

PROMPT 

QUADWORD 

READ 

RECORD 

RELEASE 

REPORT- HEADER 

SCALE 

SET 

SHOW 

SIGNED 

SORT 

STORE 

SUBSCHEMA 

SUPERSEDE 

TABLE 

THE 

TO 

TRAILING 

USAGE 

VARYING 

WHILE 

WORD 
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Table B-1: ASCII Codes 



DECIMAL 






VALUE 


CHARACTER 


REMARKS 


32 


SP 


Space 


33 


! 


Exclamation point 


34 




Double quotation mark 


35 


# 


Number sign 


36 


$ 


Dollar sign 


37 


% 


Percent sign 


38 


& 


Ampersand 


39 




Apostrophe 


40 


( 


Left (open) parenthesis 


41 


) 


Right (close) parenthesis 


42 


* 


Asterisk 


43 


+ 


Plus sign 


44 


5 


Comma 


45 




Minus sign (hyphen) 


46 




Period (decimal point) 


47 


/ 


Slash (slant) 


48 





Zero 


49 


1 


One 


50 


2 


Two 


51 


3 


Three 


52 


4 


Four 


53 


5 


Five 


54 


6 


Six 


55 


7 


Seven 


56 


8 


Eight 


57 


9 


Nine 


58 




Colon 


59 




Semicolon 




B-1 
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DECIMAL 






VALUE 


CHARACTER 


REMARKS 


60 


< 


Less than (left angle bracket) 


61 


= 


Equal sign 


62 


> 


Greater than (right angle bracket) 


63 


? 


Question mark 


64 


@ 


Commercial at sign 


65 


A 


Uppercase A 


66 


B 


Uppercase B 


67 


C 


Uppercase C 


68 


D 


Uppercase D 


69 


E 


Uppercase E 


70 


F 


Uppercase F 


71 


G 


Uppercase G 


72 


H 


Uppercase H 


73 


I 


Uppercase I 


74 


J 


Uppercase J 


75 


K 


Uppercase K 


76 


L 


Uppercase L 


77 


M 


Uppercase M 


78 


N 


Uppercase N 


79 





Uppercase 


80 


P 


Uppercase P 


81 


Q 


Uppercase Q 


82 


R 


Uppercase R 


83 


S 


Uppercase S 


84 


T 


Uppercase T 


85 


U 


Uppercase U 


86 


V 


Uppercase V 


87 


w 


Uppercase W 


88 


X 


Uppercase X 


89 


Y 


Uppercase Y 


90 


Z 


Uppercase Z 


91 


[ 


Left square bracket 


92 


\ 


Backslash (reverse slant) 


93 


] 


Right square bracket 


94 


A 


Circumflex (caret) 


95 





Underscore (underline) 


96 


V 


Left single quote (grave accent) 


97 


a 


Lowercase a 


98 


b 


Lowercase b 


99 


c 


Lowercase c 


100 


d 


Lowercase d 


101 


e 


Lowercase e 


102 


f 


Lowercase f 


103 


g 


Lowercase g 


104 


h 


Lowercase h 


105 


i 


Lowercase i 


106 


j 


Lowercase j 


107 


k 


Lowercase k 


108 


1 


Lowercase 1 


109 


m 


Lowercase m 


110 


n 


Lowercase n 
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DECIMAL 
VALUE 



CHARACTER 



REMARKS 



111 
112 
113 
114 
115 
116 
117 
118 
119 
120 
121 
122 
123 
124 
125 
126 






JjOWGrCSSG 


p 


Lowercase p 


q 


Lowercase q 


Y 


Lowercase r 


S 


Lowercase s 


t 


Lowercase t 


u 


Lowercase u 


V 


Lowercase v 


w 


Lowercase w 


X 


Lowercase x 


y 


Lowercase y 


z 


Lowercase z 


{ 


Left brace 


1 


Vertical line 


} 


Right brace 




Tilde 
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C.1 DATATRiEVE COMMANDS 



ADT Command 

ADT 

CLOSE Command 

CLOSE 

DEFINE DICTIONARY Command 

DEFINE DICTIONARY file-spec 

DEFINE DOMAIN Command 
RMS Domain 



DEFINE DOMAIN domain-name USING record-name 




ON file-spec 



View Domain 

DEFINE DOMAIN view-name OF domain-name [,...] USING 
level-number-1 field-name-1 OCCURS FOR rse-1 . 

. . u o *■ ^ o S OCCURS FOR rse-2 | 
level-number-2 field-name-2 ,- nni . , n \ 

{ FROM domain-name-2 J 



DEFINE FILE Command 
Sequential File 

DEFINE FILE [FOR] domain-name [,] 

" ALLOCATION = n " 
SUPERSEDE [,...] 
MAX J 

Indexed Sequential File 

DEFINE FILE [FOR] domain-name [,] 

"ALLOCATION = n" 
SUPERSEDE [,...] 
MAX 

{ KEY = field-name-1 [ ( [NO] CHANGE [,] [NO] DUP ) ] } [,...] 

DEFINE PORT Command 

DEFINE PORT port-name [USING] record-name ; 

DEFINE PROCEDURE Command 

DEFINE PROCEDURE procedure-name 

END-PROCEDURE 
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DEFINE RECORD Command 

DEFINE RECORD record-name [USING] 

( MAJOR-MINOR 
ALLOCATION IS ALIGNED-MAJOR-MINOR 
LEFT-RIGHT 

level-number-1 field-name-1 [field-definition-1] . 

[level-number-2 field-name-2 field-definition-2 .] 



DEFINE TABLE Command 



DEFINE TABLE table-name 



'code-1" 
code-1 

'code-2" 
code-2 



"translation-1' 
translation-1 

"translation-2' 
translation-2 



ELSE 
END_TABLE 



"translation-n' 
translation-n 



DEFINEP Command 



DEFINEP object-name 



(passwd) 



sequence-number, 



PW, new-passwd 
UIC , [m,n] 



, priv 



DELETE Command 



DELETE object-name ; 



DELETE Command (Editor) 
D[ELETE] [range] 
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DELETEP Command 

DELETEP object-name sequence-number 

EDIT Command 

EDIT object-name [ (Pa ^ Wd) ] [ADVANCED] 

EXIT Command 

\ EX ' T I 
( CTRL/Z | 

EXIT Command (Editor) 

{EX[IT]| 
{ CTRL/Z } 

EXTRACT Command 

EXTRACT [ON] file-spec object-name [,...] 

FINISH Command 

FINISH [domain-name] [,...] 

HELP Command 

HELP [ADVANCED] [topic] [,...] 

INSERT Command (Editor) 
l[NSERT] [range] 

OPEN Command 

OPEN file-spec 

QUIT Command (Editor) 
QUIT 
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READY Command 



READY / domain-name 



[(passwd)! 
(*) J 



PROTECTED 

SHARED 

EXCLUSIVE 



[AS alias-1 ; 



READ 
WRITE 
MODIFY 
EXTEND 



RELEASE Command 



RELEASE 



collection-name 

table-name 

variable-name 



[,-] 



REPLACE Command (Editor) 
R[EPLACE] [range] 

SET Command 



ABORT 
NO ABORT 
COLUMNS-PAGE = n 
SET { DICTIONARY file-spec 
GUIDE 
PROMPT 
NO PROMPT 



[-•] 



SHOW Command 



ALL 

collection-name 
COLLECTIONS 
CURRENT 
DICTIONARY 
DOMAINS 

SHOW ( FIELDS [FOR domain-name] 
object-name 
PROCEDURES 
READY 
RECORDS 
SPACE 
TABLES 



[,-.] 
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SHOWP Command 



SHOWP object-name 



(passwd) 



SUBSTITUTE Command (Editor) 



S /string— 1 /[string-2][/[range]] 



TYPE Command (Editor) 



[T[YPE]] [range] 



C.2 DATATRIEVE STATEMENTS 



ABORT Statement 

ABORT [value-expression] 

Assignment Statement 
Elementary Field 

field-name = value-expression 

Group Field 

group-field-name-1 = group-field-name-2 
Variable 

variable-name = value-expression 
AT BOTTOM Statement (Report Writer) 

(REPORT ) 
PAGE > PRINT summary-element [,...] 
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AT TOP Statement (Report Writer) 



ATT ^„^ I ?^2 RT I nniKIX (header-element ) r . 
AT TOP OF J PAGE \ PRINT summary . element [■■••] 
{ field-name j v 7 

BEGIN-END Statement 

BEGIN 

statement- 1 
[statement-2] 

END 

DECLARE Statement 

DECLARE variable-name variable-definition. 

DECLARE PORT Statement 

DECLARE PORT port-name USING 
level-number-1 field-definition-1 . 
[level-number-2 field-definition-2.] 

[level-number-n field definition-n.] 

DISPLAY Statement 

DISPLAY value-expression 

DROP Statement 

DROP [collection-name] 

END_REPORT Statement (Report Writer) 

END_REPORT 



Syntax Formats for DATATRIEVE-1 1 C-7 



ERASE Statement 

ERASE [ALL [OF rse]] 

FIND Statement 

FIND rse 

FOR Statement 

FOR rse statement 

IF-THEN-ELSE Statement 

IF boolean-expression [THEN] statement-1 [ELSE statement-2] 

MODIFY Statement 

MODIFY [ALL] f field-name [,...] 1 



L USING statement-1 J 
[VERIFY [USING] statement-2] 
[OF rse] 

PRINT Statement 

Retrieving from Selected Records and Target Record Streams Formed by FOR 
Loops 



Retrieving From Record Streams Formed by the PRINT Statement 
1. One RSE 



PRINT [print-list] 



ON 



f file-spec ) 
) *. prompt ) 



Retrieving from the Current Collection 



PRINT ALL [print-list] ON { } 



PRINT [print-list OF] rse 



ON 



( file-spec ) 
( *. prompt ) 



(continued on next page) 
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PRINT Statement (Cont.) 



Two RSEs (Inner print list follows another print list) 
PRINT print-list, ALL print-list OF rse-1 [.print-list] OF rse-2 



ON 



( file-spec ) 
{ *. prompt j 



Two RSEs (Inner print list precedes any other print list) 
PRINT ALL ALL print-list OF rse-1 [.print-list] OF rse-2 



ON 



file-spec ) 
prompt i 



PRINT Statement (Report Writer) 

PRINT print-list-element [,...] 

REPEAT Statement 

REPEAT value-expression statement 



REPORT Statement 



REPORT [rse] 



ON 



file-spec 
*. prompt 



SELECT Statement 



SELECT 



FIRST 
NEXT 
LAST 

value-expression 



[collection-name] 



SET Statement (Report Writer) 



For naming the report: 
SET REPORT_NAME = 



("string"[/...]) 
( *. prompt J 



For specifying a date or string at the upper right of each page: 
SET DATE = "string" 

(continued on next page) 
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SET Statement (Report Writer) (Cont.) 



For controlling the printing of a date or page number: 



SET 



NO DATE 
NUMBER 
NO NUMBER 



[,-] 



For specifying page width or length, or overall report length: 
COLUMNS-PAGE = 



SET 



LINES-PAGE = 
MAX_LINES = 
MAX_PAGES = 



n 

*. prompt 



[-•] 



SORT Statement 

SORT [collection-name] [BY] sort-key-1 [,...] 

STORE Statement 

STORE [context-variable IN] domain-name 
[USING statement-1] 
[VERIFY [USING] statement-2] 



SUM Statement 

SUM print-list BY sort-list 



ON 



file-spec ) 
*. prompt) 



THEN Statement 



statement-1 {THEN statement-2} [...] 



WHILE Statement 



WHILE boolean-expression statement 
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C.3 Record Definition Clauses 

ALLOCATION Clause 

I MAJOR-MINOR 
ALIGNED_MAJOR-MINOR 
LEFT-RIGHT 

COMPUTED BY Clause 

COMPUTED BY value-expression 

EDIT.STRING Clause 

EDIT-STRING [IS] edit-string 

OCCURS Clause 

Fixed Number of Occurrences 

OCCURS n TIMES 

Variable Number of Occurrences 

OCCURS min TO max TIMES DEPENDING ON field-name 

PICTURE Clause 

PIC[TURE] [IS] picture-string 

QUERY-HEADER Clause 

QUERY-HEADER [IS] {"header-segment"} [/...] 

QUERY-NAME Clause 

QUERY-NAME [IS] query-name 

REDEFINES clause 

level-no field-name-1 REDEFINES field-name-2 
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SIGN Clause 



SIGN [IS] | TRAILING | [SEPARATE] 



SORTED BY Clause 



SORT [collection-name] [BY] sort-key-1 [,...] 



USAGE Clause 



/ DISPLAY 

(COMP ) 
(INTEGER) 

fCOMP-1 ) 
( REAL J 

[USAGE [IS]] < fCOMP-2 ) 
(DOUBLE J 



fCOMP-3 
( PACKED 



(COMP-5 
(ZONED 

DATE 



VALID IF Clause 



VALID IF boolean-expression 



C.4 Miscellaneous Syntax 

Record Selection Expression 



[FIRST n 

Lall 



[context-var IN] 



domain-name 
collection-time 
list-name 



[WITH boolean-expression] 
[SORTED BY sort-key [,...]] 
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Invoke Procedure 

: procedure-name 

Invoke Command File 

@file-spec 
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See Colon 

@ 

See AT sign 



A 

ABORT statement, 5-15 to 5-18 

effect of SET ABORT, 5-15 

in STORE statement, 5-217 
Access codes, 5-67t 
Access control list 

access codes, 5-67t 

creating for ports, 5-55 

creating for procedures, 5-57 

creating for records, 5-61 

creating for RMS domains, 5-46 

creating for tables, 5-64 

creating for view domains, 5-48 

defining entries, 5-66 to 5-68 

deleting entries, 5-71 to 5-72 

displaying, 5-209 to 5-210 

SHOWP command, 5-209 to 5-210 
Access modes, 5-170t 

EXTEND, 5-170 

MODIFY, 5-170 

READ, 5-170 

required by DATATRIEVE statements, 

5-172t 
WRITE, 5-170 
Access options, 5-169t 



Accessing domains 

EXCLUSIVE, 5-169 

PROTECTED, 5-169 

READY command, 5-169 to 5-174 

restrictions, 5-170 

results, 5-171 

SHARED, 5-169 
ACL 

See Access control list 
ADT 

See Application Design Tool 
ADT command, 5-19 
Alias 

domain name, 5-169 
ALIGNED_MAJORJMINOR allocation, 

5-20 
ALL 

in RSE, 3-4 

in SHOW command, 5-206 
print list element, 5-158, 5-160 

ALLOCATION clause, 5-20 to 5-22 
ALIGNEDJMAJORJMINOR, 5-20 
in DEFINE FILE command, 5-50 
in DEFINE RECORD command, 5-60 
LEFT_RIGHT, 5-20 
MAJOR-MINOR, 5-20 

Alphanumeric fields 

edit string characters, 5-104 to 5-106 
picture string characters, 5-156 

AND Boolean operator, 2-20 

ANY relational operator, 2-19 
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Application Design Tool, 4-1 

exiting, 5-19 

invoking, 5-19 

use in definitions, 1-10 
Arithmetic expressions, 2-14 to 2-15 

evaluating, 2-14 

minus sign in, 2-14 

parentheses in, 2-14 

valid operators, 2-14t 
Arithmetic operators, 2-14t 
ASCENDING 

in SORT statement, 5-213, 5-223 

sort key, 3-7 
ASCII collating sequence, 2-18, 3-8 
Assignment statement, 5-23 to 5-30 

for elementary fields, 5-23 to 5-25 

for group fields, 5-25 to 5-27 

for variables, 5-27 to 5-30 
Asterisk (*) 

edit string character, 5-107 
AT (@) sign 

using to invoke command files, 5-13 to 
5-14 

AT BOTTOM statement (Report Writer), 
5-186 to 5-188 
summary elements, 5-187t 
AT TOP statement (Report Writer), 
5-188 to 5-191 
header and summary elements, 5-189t 
AVERAGE statistical function, 2-11 
in AT BOTTOM statement (RW), 
5-187 

in AT TOP statement (RW), 5-189 

B 

B (blank) 

edit string character, 5-105 
BE GIN-END statement, 5-31 to 5-34 

declaring variables in, 5-39 

initializing variables, 5-32 

invoking procedures from, 5-10 

restrictions, 5-31 

results, 5-31 

usage notes, 5-32 

with REPEAT statement, 5-32 
BETWEEN relational operator, 2-17 
Boolean expressions, 2-16 to 2-21 

Boolean operators, 2-20 to 2-21 

commas in, 3-7 



Boolean expressions (Cont.) 
compound, 2-21, 2-2 It 
defined, 2-1 
evaluating, 2-21 
grouping with parentheses, 2-21 
in RSE, 3-6 

relational operators, 2-17 to 2-20, 2-20t 

using, 2-16 
Boolean operators, 2-20 to 2-21 
BT 

See BETWEEN relational operator 
BUT Boolean operator, 2-20 

c 

Call Interface, 1-12 
CHANGE 

in DEFINE FILE command, 5-51 
Character set, 1-4 
Character string literals 

See Literals 
Characters 

edit string, 5-102 

floating edit string, 5-111 

picture string, 5-156 

printing, 2-2 
CLOSE command, 5-35 
COL 

in AT BOTTOM statement (RW), 
5-187 

in AT TOP statement (RW), 5-189 

print list element, 5-160 

RW print list element, 5-193 
Collections 

as record source, 3-2 

CURRENT, 3-2 

establishing with FIND, 3-2 

forming, 5-121 to 5-122 

releasing, 5-177 to 5-179 

removing records from, 5-75 to 5-79 

showing, 5-206 

sorting, 5-213 to 5-214 
Colon (:) 

using to invoke procedures, 5-10 to 
5-12 
Column headers 
in AT TOP statement (RW), 5-189 
printing, 5-161, 5-162, 5-193 
suppressing, 5-161, 5-162, 5-193 
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Comma (,) 

edit string character, 5-110 
Command files 

comments, 5-14 

creating with EXTRACT, 5-118 
default file type, 5-14 
in procedures, 5-13 
invoking, 5-13 to 5-14 
stopping execution of, 5-15 
Commands and statements, 1-2 to 1-7 
alphabetic summary, 5-3t 
complex statements, 1-3 
compound, 1-3 
continuing, 1-6 to 1-7 
differences between, 1-2 
elements of, 1-5 
functional summary, 5-6t 
functions of, 1-2 
nested, 1-3 
structure of, 1-2 
syntax, 5-1 

terminating, 1-6 to 1-7 
Comments, 1-7 

in command files, 5-14 
COMP data type, 5-229 
COMP-1 data type, 5-229 
COMP-2 data type, 5-229 
COMP-3 data type, 5-229 
COMP-5 data type, 5-230 
Compound Boolean expressions, 2-21 

evaluating, 2-2 It 
Compound statements, 1-3 

BEGIN-END, 5-31 to 5-34 

THEN, 5-226 to 5-227 

variables in, 2-8 
COMPUTED BY clause, 5-36 to 5-37 

creating virtual fields, 2-6, 5-36 

in DECLARE statement, 5-38 

in field definition, 4-7 
CON> prompt, 1-8 

Concatenated expressions, 2-2, 2-15 to 
2-16 

formatting output, 2-16 
Conditional transfers 

with IF-THEN-ELSE statement, 1-3 
CONT 

See CONTAINING relational operator 
CONTAINING relational operator, 2-17 
case-sensitivity, 2-18 



Context variables, 2-7 
in FIND statement, 3-6 
in RSE, 3-6 

qualifying field names, 2-6 

with FOR loops, 3-6 

with STORE statement, 5-219 
Continuation character, 1-6 to 1-7 

in character string literals, 2-2 
Continuation prompt, 1-8 
COUNT statistical function, 2-11 

in AT BOTTOM statement (RW), 
5-187 

in AT TOP statement (RW), 5-189 
CR (credit) 

edit string character, 5-109 
CTRL/C 

with BEGIN-END block, 5-32 
CTRL/Z 

exiting from DATATRIEVE, 5-116 
CURRENT 
in SHOW command, 5-206 

D 

Data dictionary 
defining, 5-43 to 5-44 
deleting, 5-69 

showing current, 5-44, 5-206 
Data files 

See Files 
Data types 

COMP (INTEGER), 5-229 

COMP-1 (REAL), 5-229 

COMP-2 (DOUBLE), 5-229 

COMP-3 (PACKED), 5-229 

COMP-5 (ZONED), 5-230 

DATE, 5-230 
Date 

arithmetic, 2-9 

edit string, 2-9 
DATE data type, 5-230 
Date fields 

edit string characters, 5-111 
DB (debit) 

edit string character, 5-109 
DDMF 

See Distributed Server 
Decimal point (.) 

edit string character, 5-110 
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DECLARE PORT statement, 5-41 to 
5-42 

DECLARE statement, 5-38 to 5-40 
in BEGIN-END block, 5-31, 5-39 

DECREASING 
in SORT statement, 5-213, 5-223 
sort key, 3-7 

DEFINE DICTIONARY command, 5-43 
to 5-44 

DEFINE DOMAIN command, 5-45 to 
5-49 

for RMS domains, 5-45 to 5-47 
for view domains, 5-47 to 5-49 
DEFINE FILE command, 5-50 to 5-54, 
5-173 

DEFINE PORT command, 5-55 to 5-56 
DEFINE PROCEDURE command, 5-57 
to 5-59 

DEFINE RECORD command, 4-1, 5-60 

to 5-62, 5-173 
DEFINE TABLE command, 5-63 to 5-65 
DEFINEP command, 5-66 to 5-68 
Defining 

data files, 5-50 to 5-54 
dictionaries, 5-43 to 5-44 
domains, 1-10, 5-45 to 5-49 
RMS, 5-45 to 5-47 
view, 5-47 to 5-49 
files, 1-10 

global variables, 2-8 

local variables, 2-8 

ports, 5-55 to 5-56 

privileges, 5-66 to 5-68 

procedures, 1-7, 5-57 to 5-59 

records, 1-10, 4-1 to 4-9, 5-60 to 5-62 

tables, 1-11, 5-63 to 5-65 
Definition prompt, 1-8 
DELETE command, 5-69 to 5-70 
DELETE command (Editor), 5-86 to 
5-88 

DELETEP command, 5-71 to 5-72 
Deleting 

dictionaries, 5-69 

dictionary objects, 5-69 to 5-70 

domains, 5-69 

files with SUPERSEDE clause, 5-50 
procedures, 5-69 
records, 5-69 

records in indexed files, 5-53 
tables, 5-69 



DESCENDING 

in SORT statement, 5-213, 5-223 

sort key, 3-7 
DFN> prompt, 1-8 
DICTIONARY 

in SHOW command, 5-206 
Dictionary objects 

editing, 1-11 

extracting definitions, 5-117 

extracting with QXTR, 5-119 
Dictionary tables 

See Tables 
DISPLAY statement, 5-73 to 5-74 

with FILLER fields, 4-5 
Displaying variables, 5-40 
Distributed Data Manipulation Facility 

See Distributed Server 
Distributed Server, 1-12 
Dollar sign ($) 

edit string character, 5-110 

floating edit string character, 5-111 
Domains 

accessing, 5-169 to 5-174 

alternative names, 5-169 

as record source, 3-2 

defining, 1-10, 5-45 to 5-49 
RMS, 5-45 to 5-47 
view, 5-47 to 5-49 

deleting, 5-69 

editing, 5-80 to 5-85 

hierarchical, 5-148 to 5-151 

modifying, 5-46 

showing, 5-207 
DOUBLE data type 

See COMP-2 data type 
DROP statement, 5-75 to 5-79 
DTR> prompt, 1-8 
DUP 

in DEFINE FILE command, 5-51 

E 

EDIT command, 5-80 to 5-85 
Edit string characters, 5-102t 

alphanumeric insertion, 5-105 

alphanumeric replacement, 5-104 

asterisk (*), 5-107 

B (space), 5-105 

comma (,), 5-110 

CR (credit), 5-109 
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Edit string characters (Cont.) 

date fields, 5-111 to 5-113 

DB (debit), 5-109 

decimal point (.), 5-110 

dollar sign ($), 5-110 

floating, 5-111 

floating dollar sign, 5-111 

floating minus sign, 5-111 

floating plus sign, 5-111 

for alphanumeric fields, 5-104 to 5-106 

hyphen (-), 5-105 

J (Julian date), 5-102 

M (month letter), 5-102 

minus sign (-), 5-109 

N (month number), 5-102 

9 (numeric), 5-107 

numeric fields, 5-107 to 5-113 

numeric insertion, 5-109 

numeric replacement, 5-107 

percent sign (%), 5-110 

plus sign ( + ), 5-109 

slash (/), 5-105, 5-110 

T (text), 5-105 

W (day letter), 5-102 

X (alphanumeric), 5-104 

Y (year), 5-102 

Z, 5-107 

zero (0), 5-110 
Edit strings 

date, 2-9 

for concatenated expressions, 2-16 

in PRINT statement, 5-161 

in RW PRINT statement, 5-193 
EDIT_STRING clause, 5-101 to 5-113 

in field definition, 4-7 
Editing dictionary objects, 1-11, 5-80 to 

5-85, 5-118 
Editor 

command mode, 5-82 

ending an editing session, 5-80 

IN> prompt, 1-8, 5-82, 5-90 

insert mode, 5-82 

prompts, 1-11 

QED> prompt, 1-8, 5-80 

summary, 5-8 It 

use of, 1-11 

using edited definitions, 5-84 
Editor commands, 5-80 to 5-100 
DELETE, 5-86 to 5-88 
EXIT, 5-88 to 5-89 



Editor commands (Cont.) 

INSERT, 5-90 to 5-92 

QUIT, 5-93 to 5-94 

range specifiers, 5-83t 

REPLACE, 5-94 to 5-96 

SUBSTITUTE, 5-96 to 5-98 

TYPE, 5-98 to 5-100 
Elementary fields 

alphanumeric, 4-6 

assigning values to, 5-23 to 5-25 

COMPUTED BY, 4-6 

DATE, 4-6 

defined, 1-9 

in field definition, 4-2 

names, 2-3 

numeric, 4-6 
ELSE clause 

in DEFINE TABLE command, 5-63 
END-PROCEDURE clause, 5-57 
END_REPORT statement (Report 

Writer), 5-191 
END_TABLE clause 

in DEFINE TABLE command, 5-64 
EQUAL relational operator, 2-17 
Equal sign 

in assignment statements, 5-23, 5-26, 
5-28 

ERASE statement, 5-114 to 5-115 
access mode required, 5-172 

Evaluating 

arithmetic expressions, 2-14 
Boolean expressions, 2-21, 2-2 It 

Exclamation point (!), 1-7 
in command files, 5-14 

EXCLUSIVE access option, 5-169 

EXIT command, 5-116 

EXIT command (Editor), 5-88 to 5-89 

Expressions 

arithmetic, 2-14 to 2-15 
Boolean, 2-1, 2-16 to 2-21 
concatenated, 2-2, 2-15 to 2-16 
DATE value, 2-9 
evaluating arithmetic, 2-14 
evaluating Boolean, 2-21, 2-2 It 
prompting value, 2-10 to 2-11 
statistical, 2-11 to 2-13 
table values in, 2-11 
value, 2-1, 2-1 to 2-16 

EXTEND access mode, 5-170 

EXTRACT command, 5-117 to 5-120 
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F 

Field classes, 4-6, 4-6t 
Field definitions 

clauses in, 4-7 to 4-9, 4-7t 

COMP (INTEGER), 5-229 

COMP-1 (REAL), 5-229 

COMP-2 (DOUBLE), 5-229 

COMP-3 (PACKED), 5-229 

COMP-5 (ZONED), 5-230 

components of, 4-1 

level numbers in, 4-2 to 4-3 

rules for writing, 4-8 

specifying field characteristics, 4-7 

word boundary alignment, 5-21 
Field names 

as value expressions, 2-3 

COMPUTED BY clause, 2-6 

elementary, 2-3 

FILLER, 4-4 to 4-5 

group, 2-4 to 2-5 

in AT BOTTOM statement (RW), 
5-187 

in AT TOP statement (RW), 5-189 
in field definition, 4-1, 4-3 to 4-5 
qualified, 2-3 to 2-7 
qualifying, 3-6 
REDEFINES, 2-3 
rules for, 4-3 

using as value expressions, 2-3 
using query names, 2-6 
Fields 

COMPUTED BY, 2-6, 5-23, 5-36 to 
5-37 

data types, 5-229 to 5-230 
date, 5-230 

elementary, 1-9, 2-3, 4-2 
formatting for output, 5-101 to 5-113 
formatting storage, 5-155 to 5-157, 

5-228 to 5-230 
group, 1-9, 4-2 
key, 5-51 

KEY attributes, 5-52t 
KEY defaults, 5-51t 
level numbers of, 4-3 
masking, 4-4 

multiple occurrences, 5-148 to 5-151 
redefining, 5-175 to 5-176 
showing, 5-207 



Files 

allocating storage, 5-20 to 5-22 
closing log, 5-35, 5-153 
creating, 5-50 to 5-54 
defining, 1-10, 5-50 to 5-54 
indexed, 1-10 
opening log, 5-152 
organizing, 1-10 
sequential, 1-10 
with fixed-length records, 5-51 
FILLER fields, 4-4 to 4-5 
accessing data in, 4-5 
defining, 5-60 

displaying with DISPLAY, 4-5 
FIND statement, 5-121 to 5-122 

access mode required, 5-172 

context variable in, 3-6 
FINISH command, 5-123 to 5-125 

releasing domains, 5-173 
FIRST clause 

in SELECT, 5-197 
FIRST n clause 

in RSE, 3-4 
FOR statement, 5-126 to 5-129 

controlling PRINT output, 5-161 

declaring variables in, 5-39 

invoking procedures with, 5-10 

to form record streams, 3-3 

with STORE statement, 5-218 
Formatting output 

See also Edit string characters 

date fields, 5-111 

fields, 5-101 to 5-113 

with PRINT, 5-158 to 5-165 

with the Report Writer, 1-11, 5-193 
FROM clause 

in DEFINE DOMAIN command, 5-48 
Functions 

format of statistical, 2-12 

statistical, 2-11 to 2-13 

using statistical, 2-11 

values derived with statistical, 2-1 It 

G 

GE 

See GREA TER_EQ UAL relational 
operator 
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GREATER^EQUAL relational operator, 
2-17 

GREATER_THAN relational operator, 

2-17 
Group fields 

alphanumeric, 4-6 

assigning values to, 5-25 to 5-27 

defined, 1-9 

in assignment statements, 2-4 to 2-5 
in field definition, 4-2 
qualifying, 2-6 
GT 

See GREATER-THAN relational 
operator 

H 

Halting execution 

with ABORT, 5-15 to 5-18 
HELP command, 5-130 to 5-132 
Hierarchical domains, 5-148 to 5-151 
Hyphen (-) 

as a minus sign, 1-4 

continuation character, 1-6 

conversion to underscore (_), 1-4 

edit string character, 5-105 

in string literals, 2-2 



IF-THEN-ELSE statement, 5-133 to 
5-135 

using with ABORT statement, 5-16 
IN relational operator, 2-17, 2-19 
IN> prompt, 1-8, 1-12, 5-82, 5-90 
INCREASING 

in SORT statement, 5-213, 5-223 

sort key, 3-7 
Indexed files 

creating, 5-51, 5-52 

deleting records, 5-53 

KEY field attributes, 5-52t 

KEY field defaults, 5-51t 

keys, 1-10 

modifying records in, 5-53 
Initializing 
global variables, 5-38 
local variables, 5-32, 5-39 
variables, 2-7 



INSERT command (Editor), 5-90 to 
5-92 

INTEGER data type 

See COMP data type 
Internal storage, 5-228 to 5-230 
@ (Invoke Command File) Command 

See AT 
: (Invoke procedure) 

See Colon 
Invoking 

command files, 5-13 to 5-14 

procedures, 1-7, 5-10 to 5-12, 5-58 

tables, 5-64 

J 

J (Julian date) 

edit string character, 5-102 

K 

KEY clause 

in DEFINE FILE command, 5-51 
KEY field 

attributes, 5-52t 

defaults, 5-5 It 

duplicate values in, 5-51 

modifying, 5-51 

primary, 5-51 
Keywords, 1-5 

L 

LAST 

in SELECT, 5-197 
LE 

See LESS— EQUAL relational operator 
LEFT_RIGHT allocation, 5-20 
LESS_EQUAL relational operator, 2-17 
LESS-THAN relational operator, 2-17 
Letters 

in string literals, 2-3 

in table strings, 5-63 

treatment of, 1-4 

treatment with CONTAINING, 2-18 
Level numbers 
in field definition, 4-1, 4-2 to 4-3 
rules for assigning, 4-3 
valid values, 5-61 
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Lists, 2-19 

as record source, 3-3 

creating with OCCURS FOR, 5-48 

defining with OCCURS clause, 5-148 
to 5-151 

modifying, 3-4 
Literals, 2-2 to 2-3 

character string, 2-2 to 2-3 

hyphens in, 2-2 

numeric, 2-3 

printing, 5-159 
Log files 

closing, 5-153 

opening, 5-152 
Loops 

ABORT statement in, 5-15 
FOR statement, 1-3, 5-126 to 5-129 
REPEAT statement, 1-3, 5-181 
WHILE statement, 1-3, 5-233 to 5-234 

Lowercase letters 
conversion of, 1-4 
in string literals, 2-3 

LT 

See LESS-THAN relational operator 

M 

M (month letter) 

edit string character, 5-102 
MAJOR-MINOR allocation, 5-20 
MAX clause 

in DEFINE FILE command, 5-51 
MAX statistical function, 2-11 

in AT BOTTOM statement (RW), 
5-187 

in AT TOP statement (RW), 5-189 
MIN statistical function, 2-11 
in AT BOTTOM statement (RW), 
5-187 

in AT TOP statement (RW), 5-189 
Minus sign (-) 

edit string character, 5-109 
floating edit string character, 5-111 
in arithmetic expressions, 2-14 
MODIFY access mode, 5-170 
MODIFY statement, 5-136 to 5-147 
access mode required, 5-172 
assigning field values with, 5-23, 5-26 
effect of ABORT statement, 5-16 
VERIFY clause, 5-217 



MODIFY statement (Cont.) 

with lists, 3-4 
Modifying 

access control list, 5-66 to 5-68 

domains, 5-46 

key fields, 5-51 

procedures, 5-58 

record definitions, 5-62 

records in indexed files, 5-53 

records in sequential files, 5-53 

tables, 5-65 

N 

N (month number) 

edit string character, 5-102 
Names, 1-5 to 1-6 

continuing, 1-6 

rules for, 1-5 
NE 

See NOTJEQUAL relational operator 
NEW_PAGE 
in AT BOTTOM statement (RW), 
5-187 

in AT TOP statement (RW), 5-189 
print list element, 5-160 
RW print list element, 5-193 
NEW_SECTION 
in AT BOTTOM statement (RW), 
5-187 

in AT TOP statement (RW), 5-189 

RW print list element, 5-193 
NEXT 

in SELECT, 5-197, 5-198 
9 (numeric) 

edit string character, 5-107 

picture string character, 5-156 
NO CHANGE 

in DEFINE FILE command, 5-51 
NO DUP 

in DEFINE FILE command, 5-51 
NOT BETWEEN relational operator, 
2-17 

NOT Boolean operator, 2-20 
NOT BT 
See NOT BETWEEN relational 
operator 
NOT CONT 
See NOT CONTAINING relational 
operator 



lndex-8 



NOT CONTAINING relational operator, 
2-17 

NOT IN relational operator, 2-17 

NOT_EQUAL relational operator, 2-17 

Numeric fields 
edit string characters, 5-107 to 5-113 
picture string characters, 5-156 

Numeric literals 
See Literals 

o 

OCCURS clause, 5-148 to 5-151 
fixed number of occurrences, 5-148 to 
5-149 

in field definition, 4-7 

variable number of occurrences, 5-150 
to 5-151 
OCCURS FOR clause 

in DEFINE DOMAIN command, 5-48 
OPEN command, 5-152 to 5-154 
Operators 

arithmetic, 2-14, 2-14t 

Boolean, 2-20 to 2-21 

relational, 2-17 to 2-20, 2-20t 
Optimizing 

SHOW SPACE command, 5-207 
OR Boolean operator, 2-20 

P 

P (decimal scaling) 
picture string character, 5-157 

PACKED data type 
See COMP-3 data type 

Parentheses 

in arithmetic expressions, 2-14 
in Boolean expressions, 2-21 
in statistical expressions, 2-12 

Percent sign (%) 
edit string character, 5-110 

Period 

in DECLARE statement, 5-38 
in DEFINE DOMAIN clause, 5-48 
in DEFINE RECORD command, 5-61 
in field definition, 4-1 
PICTURE clause, 5-155 to 5-157 
alphanumeric fields, 5-156 
in DECLARE statement, 5-38 
in field definition, 4-7 



PICTURE clause (Cont.) 

numeric fields, 5-156 

restrictions, 2-3 
Picture string characters 

9 (numeric), 5-156 

P (decimal scaling), 5-157 

S (sign), 5-157 

V (decimal point), 5-157 

X (alphanumeric), 5-156 
Plus sign ( + ) 

edit string character, 5-109 

floating edit string character, 5-111 
Ports 

declaring temporary, 5-41 to 5-42 

defining, 5-55 to 5-56 

global, 5-42 

local, 5-42 
PRINT statement, 5-158 to 5-165 

access mode required, 5-172 

defaults, 5-162 

print list elements, 5-160t 

print list modifiers, 5-161t 
PRINT statement (Report Writer), 5-192 

to 5-194 
Privileges 

access codes, 5-67t 

defining with DEFINEP, 5-66 to 5-68 
showing, 5-209 to 5-210 
Procedures 

defining, 1-7, 5-57 to 5-59 

deleting, 5-69 

editing, 5-80 to 5-85 

including command files in, 5-13 

invoking, 1-7, 5-10 to 5-12, 5-58 

modifying, 5-58 

nesting, 5-10 

REPEAT statements in, 5-182 
showing, 5-207 
stopping execution of, 5-15 
Prompting value expressions, 2-10 to 
2-11 

for storing and modifying values, 1-9 
for syntax, 1-9 
forming, 2-10 

in Boolean expressions, 2-18 
in loops, 2-10 
Prompts, 1-8 to 1-9 
CON>, 1-8 
DFN>, 1-8 
DTR>, 1-8 

IN>, 1-8, 1-12, 5-82, 5-90 
QED>, 1-8, 1-11, 5-80 
REMDTR>, 1-12 
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Prompts (Cont.) 

RW>, 1-8 
PROTECTED access option, 5-169 

Q 

QED> prompt, 1-8, 1-11, 5-80 
Qualified field names, 2-6 
Query names 

using, 2-6 
QUERY_HEADER clause, 5-166 to 
5-167 

in field definition, 4-4, 4-7 
QUERY_NAME clause, 5-168 

in field definition, 4-4, 4-7 
QUIT command (Editor), 5-93 to 5-94 
Quotation marks 

around string literals, 2-2 

in string literals, 2-2 
QXTR utility, 5-119 

R 

Range specifiers 

in editing commands, 5-83t 
READ access mode, 5-170 
READY 

in SHOW command, 5-207 
READY command, 5-169 to 5-174 

with PRINT statement, 5-159 
REAL data type 

See COMP-1 data type 
Record definition 

modifying, 5-62 

OCCURS clause, 5-148 to 5-151 
PICTURE clause, 5-155 to 5-157 
QUERY_HEADER clause, 5-166 to 
5-167 

QUERY_NAME clause, 5-168 
REDEFINES clause, 5-175 to 5-176 
SIGN clause, 5-211 to 5-212 
VALID IF clause, 5-231 to 5-232 

Record names 
qualifying, 2-6 

Record selection expression, 2-22 
ALL clause, 3-4 
context variable in, 3-6 
FIRST n clause, 3-4 
format, 3-1 

record source, 3-2 to 3-4 
SORTED BY clause, 3-5, 3-7 
WITH clause, 3-6 



Record stream 
forming, 3-1 
from collections, 3-2 
from domains, 3-2 
from lists, 3-3 
naming, 3-6 
sorting, 3-7 

specifying conditions, 3-6 
specifying number, 3-4 
Records 
components of, 1-9 

defining, 1-10, 4-1 to 4-9, 5-60 to 5-62 

deleting, 5-69 

editing, 5-80 to 5-85 

establishing a single record context, 

5-198 
forming streams, 3-1 
hierarchical, 2-19 
logical, 4-1 

removing from collections, 5-75 to 5-79 

selecting, 5-197 to 5-201 

showing, 5-207 

sorting, 5-213 to 5-214 

storing, 5-215 to 5-222 
REDEFINES clause, 5-175 to 5-176 

in field definition, 4-7 
Relational operators, 2-17 to 2-20, 2-20t 
RELEASE command, 5-177 to 5-179 
Releasing 

domains and collections, 5-123 to 
5-125 

global variables, 5-39, 5-40 

local variables, 5-39 
Remote Access Interface, 1-12 
Remote Terminal Interface, 1-12 

prompt, 1-12 
REPEAT statement, 5-180 to 5-182 

BEGIN-END statement in, 5-32 

declaring variables in, 5-39 

invoking procedures with, 5-10 

nesting in procedures, 5-182 

with STORE statement, 5-217 
REPLACE command (Editor), 5-94 to 
5-96 

REPORT statement, 5-183 to 5-186 

access mode required, 5-172 
Report Writer, 1-11 

AT BOTTOM statement, 5-186 to 
5-188 

AT BOTTOM statement summary 

elements, 5-187t 
AT TOP statement, 5-188 to 5-191 
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Report Writer(Cont.) 
AT TOP statement header and 
summary elements, 5-189t 
invoking, 5-183 to 5-186 
print list elements, 5-193t 
print list modifiers, 5-193t 
PRINT statement, 5-192 to 5-194 
prompt, 1-8 

SET statement, 5-194 to 5-196 
REPORTJHEADER 

in AT TOP statement (RW), 5-189 
Reports 

writing, 5-183 to 5-186 
Return (ret) , 1-6 
RMS domains 

defining, 5-45 to 5-47 
RSE 

See Record selection expression 
RW> prompt, 1-8 



S (sign) 

picture string characters, 5-157 

SELECT statement, 5-197 to 5-201 
with DROP statement, 5-198 

Semicolon, 1-6 
in DECLARE PORT statement, 5-41 
in DEFINE DOMAIN clause, 5-48 
in DEFINE PORT command, 5-55 
in DEFINE RECORD command, 5-61 
in DELETE command, 5-69 
in domain definition, 5-46 

Sequential files, 1-10 
creating, 5-51, 5-52 
modifying records in, 5-53 

SET ABORT command, 5-202, 5-204 
effect on ABORT statement, 5-15 
with REPEAT statement, 5-181 

SET COLUMNS_PAGE command, 
5-202, 5-204 

SET command, 5-202 to 5-205 

SET DICTIONARY command, 5-203, 
5-204 

SET GUIDE command, 5-203 
SET NO ABORT command, 5-202, 
5-204 

SET NO PROMPT command, 5-203 
SET PROMPT command, 5-203 
SET statement (Report Writer), 5-194 to 
5-196 

COLUMNS_PAGE, 5-194 
DATE, 5-196 
LINES_PAGE, 5-194 



SET statement (Report Writer) (Cont.) 

MAX_LINES, 5-194 

MAX_PAGES, 5-194 

NUMBER, 5-196 

REPORT_NAME, 5-196 
SHARED access option, 5-169 
SHOW ALL command, 5-206 
SHOW COLLECTIONS command, 

5-178, 5-206 
SHOW command, 5-199, 5-206 to 5-208 
SHOW CURRENT command, 5-206 
SHOW DICTIONARY command, 5-206 
SHOW DOMAINS command, 5-207 
SHOW FIELDS command, 5-178, 5-207 
SHOW PROCEDURES command, 5-207 
SHOW READY command, 5-172, 5-178, 
5-207 

SHOW RECORDS command, 5-207 
SHOW SPACE command, 5-207 
SHOW TABLES command, 5-207 
SHOWP command, 5-209 to 5-210 
SIGN clause, 5-211 to 5-212 

in field definition, 4-7 

LEADING, 5-211 

SEPARATE, 5-211 

TRAILING, 5-211 
SKIP 

in AT BOTTOM statement (RW), 
5-187 

in AT TOP statement (RW), 5-189 
print list element, 5-160 
RW print list element, 5-193 
Slash (/) 

edit string character, 5-105, 5-110 
Sort keys 

ASCENDING, 3-7 

DESCENDING, 3-7 

in SORT statement, 5-213 

in SUM statement, 5-223 

multiple, 3-8 
SORT statement, 5-213 to 5-214 

access mode required, 5-172 

ASCENDING order, 5-213, 5-223 

DECREASING order, 5-213, 5-223 

DESCENDING order, 5-213, 5-223 

INCREASING order, 5-213, 5-223 
SORTED BY clause 

format, 3-7 

in RSE, 3-7 

sort keys, 3-7 
SPACE 

in AT BOTTOM statement (RW), 
5-187 

in AT TOP statement (RW), 5-189 
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SPACE (Cont.) 

in SHOW command, 5-207 

print list element, 5-160 

RW print list element, 5-193 
Specifying ranges 

in editing commands, 5-83 
Statements 

See Commands and statements 
Statistical expressions, 2-11 to 2-13 

RSE in, 2-13 
Statistical functions, 2- lit 
STORE statement, 5-215 to 5-222 

access mode required, 5-172 

assigning field values with, 5-23, 5-26 

effect of ABORT statement, 5-16 

in FOR statement, 5-218 

prompts, 5-216 

VERIFY clause, 5-217 
SUBSTITUTE command (Editor), 5-96 
to 5-98 

SUM statement, 5-223 to 5-225 

access mode required, 5-172 
SUPERSEDE clause 

in DEFINE FILE command, 5-50 
Syntax 

commands and statements, 5-1 
keywords in, 1-5 

symbols and conventions, 5-2, 5-2t 

T 

T (text) 

edit string character, 5-105 
TAB 

in AT BOTTOM statement (RW), 
5-187 

in AT TOP statement (RW), 5-189 
print list element, 5-160 
RW print list element, 5-193 
Tables 

code/translation strings, 5-63 
comparing with IN, 2-19 
default edit string, 5-64 
defining, 1-11, 5-63 to 5-65 
deleting, 5-69 
editing, 5-80 to 5-85 
functions and uses of, 1-11 
in value expressions, 2-11 
invoking, 5-64 
modifying, 5-65 
releasing, 5-177 to 5-179 
retrieving values with VIA, 2-11 
showing, 5-207 



Termination characters, 1-6 to 1-7 

Return © , 1-6 

semicolon, 1-6 
THEN statement, 5-226 to 5-227 
TODAY value expression, 2-9 
TOTAL statistical function, 2-11 

in AT BOTTOM statement (RW), 
5-187 

in AT TOP statement (RW), 5-189 
Totals 

SUM statement, 5-224 
Transferring control 

with ABORT, 5-15 
Transfers 

with IF-THEN-ELSE statement, 1-3 
TYPE command (Editor), 5-98 to 5-100 

u 

Underscore (_), 1-4 
Uppercase letters 

in string literals, 2-3 
USAGE clause, 5-228 to 5-230 

COMP data type, 5-229 

COMP-1 data type, 5-229 

COMP-2 data type, 5-229 

COMP-3 data type, 5-229 

COMP-5 data type, 5-230 

DATE, 5-230 

in DECLARE statement, 5-38 
in field definition, 4-7 
USING clause 

in PRINT statement, 5-161 

in RW PRINT statement, 5-193 

in STORE statement, 5-215 



V 

V (decimal point) 

picture string character, 5-157 
VALID IF clause, 5-24, 5-28, 5-231 to 
5-232 

in field definition, 4-7 
Value expressions 

concatenated, 2-15 to 2-16 
DATE, 2-9 to 2-10 
defined, 2-1 

displaying, 5-73 to 5-74 
global variables in, 2-8 
in arithmetic expressions, 2-14 to 2-15 
in AT BOTTOM statement (RW), 
5-187 
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Value expressions (Cont.) 
in AT TOP statement (RW), 5-189 
local variables in, 2-8 
prompting, 2-10 to 2-11 
statistical, 2-11 to 2-13 
table, 2-11 
TODAY, 2-9 
types of, 2-1 
use of, 2-1 

variables in, 2-7 to 2-9 
Variables 

assigning values to, 5-27 to 5-30, 5-39 
context, 2-6 

declaring, 2-7, 5-38 to 5-40 

defining global, 2-8, 5-38 

defining local, 2-8, 5-31 

displaying with SHOW FIELDS, 5-40 

formatting for output, 5-101 to 5-113 

in value expressions, 2-7 to 2-9 

initializing, 2-7 

initializing global, 5-38 

initializing local, 5-32 

releasing global, 2-8, 5-40, 5-177 to 
5-179 
VERIFY clause 

in MODIFY statement, 5-217 

in STORE statement, 5-217, 5-220 
VERIFY USING clause 

in STORE statement, 5-215, 5-217 
VIA clause, 2-11, 5-64 
View domains 

defining, 5-47 to 5-49 



Virtual fields 
See COMPUTED BY clause 

w 

W (day letter) 

edit string character, 5-102 
WHILE statement, 5-233 to 5-234 

with STORE statement, 5-220 
WITH clause 

in RSE, 3-6 
WRITE access mode, 5-170 

X 

X (alphanumeric) 
edit string character, 5-104 
picture string character, 5-156 

Y 

Y (year) 

edit string character, 5-102 

z 

Z 

edit string character, 5-107 
Zero (0) 

edit string character, 5-110 
ZONED data type 

See COMP-5 data type 
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